refactor: clarify component registration scope and improve documentation

Update documentation and code comments to enhance clarity around component registration scope, replacing terms like "package scanning path" with "registration scope." Adjust exception messages and method descriptions to reflect the new terminology and improve understanding of component registration processes. Ensure consistency across annotations and exception handling related to component registration.

Author: codeboyzhou

docs/components.md

@@ -211,7 +211,7 @@ public class MyPromptCompletions {
 
 ## Automatic Registration
 
-After defining MCP components, they will be automatically registered to the server. You just need to ensure that the component classes are in the package scanning path of the server application.
+After defining MCP components, they will be automatically registered to the server. You just need to ensure that the component classes are within the registration scope of the server application.
 
 ### One instance per component class
 
@@ -235,7 +235,7 @@ If you need to specify a specific package path, you can use the following method
 @McpServerApplication(basePackage = "com.example.mcp.components")
 ```
 
-If no package path is specified, the package of the class passed to `McpApplication.run()` will be scanned.
+If no package path is specified, the package of the class passed to `McpApplication.run()` is used as the default registration scope.
 
 ## Structured Content
 

src/main/java/com/github/thought2code/mcp/annotated/McpApplication.java

@@ -22,8 +22,8 @@
  * <p>This class provides the entry point for running MCP servers with annotation-based
  * configuration. It supports STDIO and STREAMABLE modes. {@link ServerMode#SSE} is deprecated but
  * still supported for backward compatibility. The application automatically loads configuration,
- * initializes reflection scanning, and starts the appropriate server based on the configuration
- * settings.
+ * resolves component registration scope, and starts the appropriate server based on the
+ * configuration settings.
  *
  * @author codeboyzhou
  */
@@ -39,10 +39,11 @@ private McpApplication() {
   /**
    * Runs the MCP application with the specified main class and command-line arguments.
    *
-   * <p>This method initializes the reflection provider and starts the MCP server based on the
+   * <p>This method resolves application context scope and starts the MCP server based on the
    * configuration settings.
    *
-   * @param mainClass the main class of the application, used as the base for reflection scanning
+   * @param mainClass the main class of the application, used to resolve component registration
+   *     scope
    * @param args the command-line arguments passed to the application
    * @param configFileName the name of the configuration file to load
    * @see McpApplicationContext
@@ -58,10 +59,11 @@ public static void run(Class<?> mainClass, String[] args, String configFileName)
    * Runs the MCP application with the specified main class and command-line arguments using the
    * default configuration file.
    *
-   * <p>This method initializes the reflection provider and starts the MCP server based on the
+   * <p>This method resolves application context scope and starts the MCP server based on the
    * configuration settings.
    *
-   * @param mainClass the main class of the application, used as the base for reflection scanning
+   * @param mainClass the main class of the application, used to resolve component registration
+   *     scope
    * @param args the command-line arguments passed to the application
    */
   public static void run(Class<?> mainClass, String[] args) {

src/main/java/com/github/thought2code/mcp/annotated/McpApplicationContext.java

@@ -11,8 +11,8 @@
 /**
  * Runtime context for one annotated MCP application.
  *
- * <p>In the build-time component architecture, this context no longer performs classpath scanning.
- * Instead, it centralizes runtime concerns that component invokers still need:
+ * <p>In the build-time component architecture, this context no longer performs runtime classpath
+ * discovery. Instead, it centralizes runtime concerns that component invokers still need:
  *
  * <ul>
  *   <li>Component instance lifecycle (lazy creation with one cached instance per component class)

src/main/java/com/github/thought2code/mcp/annotated/annotation/McpServerApplication.java

@@ -9,7 +9,7 @@
 /**
  * This annotation is used to mark a class as an MCP (Model Context Protocol) server application.
  *
- * <p>The base package for component scanning can be specified via the {@code basePackage}
+ * <p>The base package for component registration scope can be specified via the {@code basePackage}
  * attribute. If not specified, the package of the annotated class will be used.
  *
  * <p>Example usage:
@@ -29,19 +29,20 @@
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpServerApplication {
   /**
-   * The base package for component scanning. Defaults to the package of the annotated class.
+   * The base package for component registration scope. Defaults to the package of the annotated
+   * class.
    *
-   * @return the base package for component scanning
+   * @return the base package for component registration scope
    */
   String basePackage() default StringHelper.EMPTY;
 
   /**
-   * The base package class for component scanning. Defaults to {@code Object.class}.
+   * The base package class for component registration scope. Defaults to {@code Object.class}.
    *
    * <p>Note: This attribute is intended to be used when the base package cannot be determined
    * statically. In most cases, {@link #basePackage()} should be used instead.
    *
-   * @return the base package class for component scanning
+   * @return the base package class for component registration scope
    */
   Class<?> basePackageClass() default Object.class;
 }

src/main/java/com/github/thought2code/mcp/annotated/exception/McpServerComponentRegistrationException.java

@@ -12,7 +12,7 @@
  *   <li>Missing or incorrect annotations on component methods
  *   <li>Dependency injection failures during component creation
  *   <li>Configuration errors in component metadata
- *   <li>Reflection-related errors during component discovery
+ *   <li>Build-time model loading or runtime registration failures
  * </ul>
  *
  * <p>This exception extends {@link McpServerException} and is part of the MCP annotated framework's
@@ -45,9 +45,9 @@ public McpServerComponentRegistrationException(String message) {
    * another exception. The cause exception is preserved and can be accessed later for detailed
    * error analysis and debugging.
    *
-   * <p>Common causes include reflection exceptions, dependency injection failures, or validation
-   * errors during component creation. The message should provide context about the registration
-   * operation that failed.
+   * <p>Common causes include component instantiation failures, build-time model loading issues, or
+   * validation errors during component registration. The message should provide context about the
+   * registration operation that failed.
    *
    * @param message the detail message explaining the reason for the exception, may be null but
    *     should provide meaningful error information

src/main/java/com/github/thought2code/mcp/annotated/server/AnnotatedMcpServer.java

@@ -81,9 +81,8 @@ public interface AnnotatedMcpServer {
    * Registers all MCP server components (resources, prompts, tools) with the specified synchronous
    * server instance.
    *
-   * <p>This method should scan for annotated methods and register them as appropriate MCP
-   * components with the server. Components are discovered using reflection and registered through
-   * the component registry.
+   * <p>This method should load build-time generated component definitions and register the in-scope
+   * components with the server.
    *
    * @param mcpSyncServer the synchronous server instance to register components with
    */
@@ -93,9 +92,8 @@ public interface AnnotatedMcpServer {
    * Registers all MCP server components (resources, prompts, tools) with the specified asynchronous
    * server instance.
    *
-   * <p>This method should scan for annotated methods and register them as appropriate MCP
-   * components with the server. Components are discovered using reflection and registered through
-   * the component registry.
+   * <p>This method should load build-time generated component definitions and register the in-scope
+   * components with the server.
    *
    * @param mcpAsyncServer the asynchronous server instance to register components with
    */

src/main/java/com/github/thought2code/mcp/annotated/server/component/AnnotationProcessor.java

@@ -368,7 +368,10 @@ private void writeProvider() throws IOException {
       writer.write("import org.slf4j.Logger;\n");
       writer.write("import org.slf4j.LoggerFactory;\n\n");
       writer.write("public final class " + className + " implements ComponentProvider {\n\n");
-      writer.write("  private static final Logger log = LoggerFactory.getLogger(" + className + ".class);\n\n");
+      writer.write(
+          "  private static final Logger log = LoggerFactory.getLogger("
+              + className
+              + ".class);\n\n");
 
       writer.write("  @Override\n");
       writer.write("  public List<ToolDefinition> tools() {\n");

src/main/java/com/github/thought2code/mcp/annotated/server/component/Invocation.java

@@ -3,7 +3,7 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
- * This record represents the result of reflection invocation of Java method.
+ * This record represents the result of invoking one generated MCP component binding.
  *
  * @author codeboyzhou
  */

src/main/java/com/github/thought2code/mcp/annotated/server/component/InvocationLogMessageHelper.java

@@ -5,8 +5,7 @@ public final class InvocationLogMessageHelper {
 
   private InvocationLogMessageHelper() {}
 
-  public static final String TOOL_INVOCATION_FAILED =
-      "Tool invocation failed for sourceMethod={}";
+  public static final String TOOL_INVOCATION_FAILED = "Tool invocation failed for sourceMethod={}";
 
   public static final String PROMPT_INVOCATION_FAILED =
       "Prompt invocation failed for sourceMethod={}";

src/test/java/com/github/thought2code/mcp/annotated/server/component/DuplicateComponentMessageHelperTest.java

@@ -13,18 +13,24 @@ class DuplicateComponentMessageHelperTest {
   @ParameterizedTest
   @MethodSource("duplicateNameMessageCases")
   void duplicateNameMessage_shouldMatchTemplate(
-      String componentKind, String name, String previousMethod, String currentMethod, String expected) {
+      String componentKind,
+      String name,
+      String previousMethod,
+      String currentMethod,
+      String expected) {
     String actual =
         switch (componentKind) {
           case "tool" ->
-              DuplicateComponentMessageHelper.duplicateToolName(name, previousMethod, currentMethod);
+              DuplicateComponentMessageHelper.duplicateToolName(
+                  name, previousMethod, currentMethod);
           case "prompt" ->
               DuplicateComponentMessageHelper.duplicatePromptName(
                   name, previousMethod, currentMethod);
           case "resource" ->
               DuplicateComponentMessageHelper.duplicateResourceName(
                   name, previousMethod, currentMethod);
-          default -> throw new IllegalArgumentException("Unsupported component kind: " + componentKind);
+          default ->
+              throw new IllegalArgumentException("Unsupported component kind: " + componentKind);
         };
     assertEquals(expected, actual);
   }
@@ -86,7 +92,8 @@ private static Stream<Arguments> duplicateCompletionMessageCases() {
   private static Stream<Arguments> completionReferenceDescriptionCases() {
     return Stream.of(
         Arguments.of(
-            McpSchema.PromptReference.builder("generateCode").build(), "prompt name 'generateCode'"),
+            McpSchema.PromptReference.builder("generateCode").build(),
+            "prompt name 'generateCode'"),
         Arguments.of(new McpSchema.ResourceReference("file://"), "resource uri 'file://'"),
         Arguments.of(null, "'null'"));
   }