refactor: simplify McpConfigurationChecker structure and error keys.

Split validation into focused helpers, prefix nested config keys for clearer errors, and remove unused merge-era check overloads.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: codeboyzhou

src/main/java/com/github/thought2code/mcp/annotated/configuration/McpConfigurationChecker.java

@@ -16,31 +16,29 @@
  * @author codeboyzhou
  */
 public final class McpConfigurationChecker {
-  /**
-   * Private constructor to prevent instantiation of this utility class.
-   *
-   * @throws UnsupportedOperationException always thrown when attempting to instantiate
-   */
+
   private McpConfigurationChecker() {
     throw new UnsupportedOperationException("Utility class should not be instantiated");
   }
 
   /**
    * Performs comprehensive validation of the MCP server configuration.
    *
-   * <p>This method validates all required configuration properties including:
-   *
-   * <ul>
-   *   <li>Basic server information (enabled, mode, name, version, type, instructions)
-   *   <li>Timeout and capabilities settings
-   *   <li>Change notification configuration
-   *   <li>Mode-specific settings (SSE or STREAMABLE)
-   * </ul>
-   *
    * @param configuration the MCP server configuration to validate
    * @throws McpServerConfigurationException if any required configuration property is missing
    */
   public static void check(McpServerConfiguration configuration) {
+    checkCore(configuration);
+    checkCapabilities(configuration.capabilities());
+    checkChangeNotification(configuration.changeNotification());
+    switch (configuration.mode()) {
+      case SSE -> checkSse(configuration.sse());
+      case STREAMABLE -> checkStreamable(configuration.streamable());
+      case STDIO -> {}
+    }
+  }
+
+  private static void checkCore(McpServerConfiguration configuration) {
     checkNull("enabled", configuration.enabled());
     checkNull("mode", configuration.mode());
     checkBlank("name", configuration.name());
@@ -49,114 +47,56 @@ public static void check(McpServerConfiguration configuration) {
     checkBlank("instructions", configuration.instructions());
     checkNull("request-timeout", configuration.requestTimeout());
     checkNull("capabilities", configuration.capabilities());
-    checkNull("resource", configuration.capabilities().resource());
-    if (configuration.capabilities().resource()) {
-      checkNull("subscribe-resource", configuration.capabilities().subscribeResource());
-    }
-    checkNull("prompt", configuration.capabilities().prompt());
-    checkNull("tool", configuration.capabilities().tool());
-    checkNull("completion", configuration.capabilities().completion());
     checkNull("change-notification", configuration.changeNotification());
-    checkNull("resource", configuration.changeNotification().resource());
-    checkNull("prompt", configuration.changeNotification().prompt());
-    checkNull("tool", configuration.changeNotification().tool());
-    if (configuration.mode() == ServerMode.SSE) {
-      checkSse(configuration);
-    }
-    if (configuration.mode() == ServerMode.STREAMABLE) {
-      checkNull("streamable", configuration.streamable());
-      checkBlank("mcp-endpoint", configuration.streamable().mcpEndpoint());
-      checkNull("disallow-delete", configuration.streamable().disallowDelete());
-      checkNull("keep-alive-interval", configuration.streamable().keepAliveInterval());
-      checkNull("port", configuration.streamable().port());
+  }
+
+  private static void checkCapabilities(McpServerCapabilities capabilities) {
+    checkNull("capabilities.resource", capabilities.resource());
+    if (capabilities.resource()) {
+      checkNull("capabilities.subscribe-resource", capabilities.subscribeResource());
     }
+    checkNull("capabilities.prompt", capabilities.prompt());
+    checkNull("capabilities.tool", capabilities.tool());
+    checkNull("capabilities.completion", capabilities.completion());
+  }
+
+  private static void checkChangeNotification(McpServerChangeNotification changeNotification) {
+    checkNull("change-notification.resource", changeNotification.resource());
+    checkNull("change-notification.prompt", changeNotification.prompt());
+    checkNull("change-notification.tool", changeNotification.tool());
   }
 
   /**
    * Validates SSE-specific configuration properties.
    *
-   * @param configuration the MCP server configuration to validate
+   * @param sse SSE configuration to validate
    * @deprecated HTTP SSE mode is deprecated; use {@link ServerMode#STREAMABLE} instead.
    */
   @Deprecated(since = "0.16.0", forRemoval = true)
-  private static void checkSse(McpServerConfiguration configuration) {
-    checkNull("sse", configuration.sse());
-    checkBlank("message-endpoint", configuration.sse().messageEndpoint());
-    checkBlank("endpoint", configuration.sse().endpoint());
-    checkBlank("base-url", configuration.sse().baseUrl());
-    checkNull("port", configuration.sse().port());
+  private static void checkSse(McpServerSSE sse) {
+    checkNull("sse", sse);
+    checkBlank("sse.message-endpoint", sse.messageEndpoint());
+    checkBlank("sse.endpoint", sse.endpoint());
+    checkBlank("sse.base-url", sse.baseUrl());
+    checkNull("sse.port", sse.port());
   }
 
-  /**
-   * Validates that at least one of two configuration values is not null.
-   *
-   * <p>This method is typically used to validate profile-based configurations where a base value
-   * and a profile-specific value can both provide the same configuration property. At least one of
-   * them must be non-null.
-   *
-   * @param <T> the type of the configuration values
-   * @param configKey the configuration key name used for error reporting
-   * @param baseValue the base configuration value
-   * @param profileValue the profile-specific configuration value
-   * @throws McpServerConfigurationException if both values are null
-   */
-  public static <T> void checkNull(String configKey, T baseValue, T profileValue) {
-    if (baseValue == null && profileValue == null) {
-      throw new McpServerConfigurationException(
-          String.format("Missing config key '%s' in the configuration file.", configKey));
-    }
+  private static void checkStreamable(McpServerStreamable streamable) {
+    checkNull("streamable", streamable);
+    checkBlank("streamable.mcp-endpoint", streamable.mcpEndpoint());
+    checkNull("streamable.disallow-delete", streamable.disallowDelete());
+    checkNull("streamable.keep-alive-interval", streamable.keepAliveInterval());
+    checkNull("streamable.port", streamable.port());
   }
 
-  /**
-   * Validates that a single configuration value is not null.
-   *
-   * <p>This method performs a simple null check on a configuration value and throws an exception if
-   * the value is null, indicating that a required configuration property is missing.
-   *
-   * @param <T> the type of the configuration value
-   * @param configKey the configuration key name used for error reporting
-   * @param value the configuration value to validate
-   * @throws McpServerConfigurationException if the value is null
-   */
-  public static <T> void checkNull(String configKey, T value) {
+  private static <T> void checkNull(String configKey, T value) {
     if (value == null) {
       throw new McpServerConfigurationException(
           String.format("Missing config key '%s' in the configuration file.", configKey));
     }
   }
 
-  /**
-   * Validates that at least one of two string configuration values is not blank.
-   *
-   * <p>This method is typically used to validate profile-based configurations where a base value
-   * and a profile-specific value can both provide the same string configuration property. At least
-   * one of them must be non-blank. A value is considered blank if it is null, empty, or contains
-   * only whitespace.
-   *
-   * @param configKey the configuration key name used for error reporting
-   * @param baseValue the base configuration string value
-   * @param profileValue the profile-specific configuration string value
-   * @throws McpServerConfigurationException if both values are blank
-   */
-  public static void checkBlank(String configKey, String baseValue, String profileValue) {
-    if (StringHelper.isBlank(baseValue) && StringHelper.isBlank(profileValue)) {
-      throw new McpServerConfigurationException(
-          String.format("Missing config key '%s' in the configuration file.", configKey));
-    }
-  }
-
-  /**
-   * Validates that a single string configuration value is not blank.
-   *
-   * <p>This method performs a blank check on a string configuration value and throws an exception
-   * if the value is blank. A value is considered blank if it is null, empty, or contains only
-   * whitespace.
-   *
-   * @param configKey the configuration key name used for error reporting
-   * @param value the configuration string value to validate
-   * @throws McpServerConfigurationException if the value is blank
-   */
-  public static void checkBlank(String configKey, String value) {
+  private static void checkBlank(String configKey, String value) {
     if (StringHelper.isBlank(value)) {
       throw new McpServerConfigurationException(
           String.format("Missing config key '%s' in the configuration file.", configKey));

src/test/java/com/github/thought2code/mcp/annotated/configuration/McpConfigurationCheckerTest.java

@@ -56,7 +56,7 @@ void check_shouldRejectMissingSubscribeResourceWhenResourceEnabled() {
         assertThrows(
             McpServerConfigurationException.class,
             () -> McpConfigurationChecker.check(configuration));
-    assertTrue(exception.getMessage().contains("subscribe-resource"));
+    assertTrue(exception.getMessage().contains("capabilities.subscribe-resource"));
   }
 
   @Test
@@ -72,20 +72,13 @@ void check_shouldRejectMissingSseSettingsWhenModeIsSse() {
   }
 
   @Test
-  void checkNull_shouldRejectWhenBothValuesAreNull() {
-    McpServerConfigurationException exception =
-        assertThrows(
-            McpServerConfigurationException.class,
-            () -> McpConfigurationChecker.checkNull("mode", null, null));
-    assertTrue(exception.getMessage().contains("mode"));
-  }
-
-  @Test
-  void checkBlank_shouldRejectWhenBothValuesAreBlank() {
+  void check_shouldRejectMissingStreamableSettingsWhenModeIsStreamable() {
+    McpServerConfiguration configuration =
+        TestMcpConfigurations.baseBuilder().mode(ServerMode.STREAMABLE).streamable(null).build();
     McpServerConfigurationException exception =
         assertThrows(
             McpServerConfigurationException.class,
-            () -> McpConfigurationChecker.checkBlank("name", "  ", null));
-    assertTrue(exception.getMessage().contains("name"));
+            () -> McpConfigurationChecker.check(configuration));
+    assertTrue(exception.getMessage().contains("streamable"));
   }
 }