Register MCP components at compile time via McpToolModelProcessor instead of runtime reflection and classpath scanning, improving startup and simplifying the server bootstrap path.

Author: codeboyzhou

pom.xml

@@ -62,7 +62,6 @@
         <logback.version>1.5.33</logback.version>
         <mcp-sdk.version>2.0.0-M3</mcp-sdk.version>
         <mockito.version>5.23.0</mockito.version>
-        <reflections.version>0.10.2</reflections.version>
     </properties>
 
     <dependencyManagement>
@@ -111,11 +110,6 @@
             <version>${mockito.version}</version>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>org.reflections</groupId>
-            <artifactId>reflections</artifactId>
-            <version>${reflections.version}</version>
-        </dependency>
     </dependencies>
 
     <build>
@@ -184,6 +178,19 @@
                         <arg>-Xlint:deprecation</arg>
                     </compilerArgs>
                 </configuration>
+                <executions>
+                    <execution>
+                        <id>default-compile</id>
+                        <configuration>
+                            <!--
+                              This module ships annotation processors for downstream consumers.
+                              Disable processor execution while compiling this module itself to avoid
+                              service-loader bootstrap failures before processor classes are compiled.
+                            -->
+                            <proc>none</proc>
+                        </configuration>
+                    </execution>
+                </executions>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>

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

@@ -1,77 +1,144 @@
 package com.github.thought2code.mcp.annotated;
 
-import com.github.thought2code.mcp.annotated.reflect.ReflectionsProvider;
-import com.github.thought2code.mcp.annotated.server.component.DefaultMcpComponentInstanceFactory;
-import com.github.thought2code.mcp.annotated.server.component.McpComponentInstanceFactory;
-import java.lang.annotation.Annotation;
-import java.lang.reflect.Field;
-import java.lang.reflect.Method;
+import com.github.thought2code.mcp.annotated.annotation.McpServerApplication;
+import com.github.thought2code.mcp.annotated.enums.McpServerError;
+import com.github.thought2code.mcp.annotated.exception.McpServerException;
+import com.github.thought2code.mcp.annotated.util.StringHelper;
 import java.util.Objects;
-import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
 
 /**
  * Runtime context for one annotated MCP application.
  *
- * <p>The context owns application-scoped services such as classpath scanning. This keeps
- * independent MCP applications from sharing global mutable state when they run in the same JVM.
+ * <p>In the build-time compiled architecture, this context no longer performs classpath scanning.
+ * Instead, it centralizes runtime concerns that compiled invokers still need:
+ *
+ * <ul>
+ *   <li>Component instance lifecycle (lazy creation with one cached instance per component class)
+ *   <li>Scope filtering for compiled model definitions based on the resolved application base
+ *       package
+ * </ul>
+ *
+ * <p>Each application gets its own context instance so multiple MCP applications can run in the
+ * same JVM without sharing component instances or scope rules.
  */
 public final class McpApplicationContext {
-  /** The reflections provider used to scan the application's classpath for annotated components. */
-  private final ReflectionsProvider reflectionsProvider;
+  /** Base package resolved from {@link McpServerApplication}. */
+  private final String basePackage;
 
-  /** The factory used to create or locate annotated component instances. */
-  private final McpComponentInstanceFactory componentInstanceFactory;
+  /** Component instance cache; one instance per component class. */
+  private final ConcurrentMap<Class<?>, Object> componentInstances = new ConcurrentHashMap<>();
 
-  private McpApplicationContext(
-      ReflectionsProvider reflectionsProvider,
-      McpComponentInstanceFactory componentInstanceFactory) {
-    this.reflectionsProvider =
-        Objects.requireNonNull(reflectionsProvider, "reflectionsProvider must not be null");
-    this.componentInstanceFactory =
-        Objects.requireNonNull(
-            componentInstanceFactory, "componentInstanceFactory must not be null");
+  private McpApplicationContext(String basePackage) {
+    this.basePackage = Objects.requireNonNull(basePackage, "basePackage must not be null");
   }
 
   /**
    * Creates a new context for the specified MCP application class.
    *
-   * @param mainClass the application entry class used for package scanning
+   * <p>The resolved base package follows this priority:
+   *
+   * <ol>
+   *   <li>{@link McpServerApplication#basePackageClass()} when explicitly set
+   *   <li>{@link McpServerApplication#basePackage()} when non-blank
+   *   <li>the package of {@code mainClass} as fallback
+   * </ol>
+   *
+   * @param mainClass the application entry class used to resolve base-package scope
    * @return a new application-scoped context
    */
   public static McpApplicationContext from(Class<?> mainClass) {
-    ReflectionsProvider reflectionsProvider =
-        ReflectionsProvider.initializeReflectionsInstance(mainClass);
-    return new McpApplicationContext(
-        reflectionsProvider, DefaultMcpComponentInstanceFactory.create());
+    Objects.requireNonNull(mainClass, "mainClass must not be null");
+    return new McpApplicationContext(resolveBasePackage(mainClass));
   }
 
   /**
-   * Returns all methods annotated with the specified annotation within this context's scan scope.
+   * Returns a component instance for the specified component class.
+   *
+   * <p>Instances are created lazily via the no-argument constructor and cached per declaring class.
+   * Repeated calls for the same class return the same instance.
    *
-   * @param annotation the annotation class to search for
-   * @return methods annotated with the given annotation
+   * @param componentClass the class declaring annotated MCP component methods
+   * @return the component instance to invoke
    */
-  public Set<Method> getMethodsAnnotatedWith(Class<? extends Annotation> annotation) {
-    return reflectionsProvider.getMethodsAnnotatedWith(annotation);
+  public Object getComponentInstance(Class<?> componentClass) {
+    Objects.requireNonNull(componentClass, "componentClass must not be null");
+    return componentInstances.computeIfAbsent(
+        componentClass, McpApplicationContext::createInstance);
   }
 
   /**
-   * Returns all fields annotated with the specified annotation within this context's scan scope.
+   * Returns whether a compiled source method belongs to this application's base package scope.
+   *
+   * <p>This method is used while loading compiled definitions to prevent out-of-scope components
+   * from being registered (for example, fixtures from other test packages or neighboring modules).
    *
-   * @param annotation the annotation class to search for
-   * @return fields annotated with the given annotation
+   * @param sourceMethod compiled source method descriptor in the form {@code fqcn#method(...)}
+   * @return {@code true} when the source method declaring class is within the configured base
+   *     package
    */
-  public Set<Field> getFieldsAnnotatedWith(Class<? extends Annotation> annotation) {
-    return reflectionsProvider.getFieldsAnnotatedWith(annotation);
+  public boolean isInScope(String sourceMethod) {
+    if (StringHelper.isBlank(sourceMethod)) {
+      return false;
+    }
+
+    final int hashIndex = sourceMethod.indexOf(StringHelper.HASH);
+    final String declaringClassName =
+        (hashIndex >= 0 ? sourceMethod.substring(0, hashIndex) : sourceMethod).trim();
+    if (declaringClassName.isEmpty()) {
+      return false;
+    }
+
+    if (basePackage.isEmpty()) {
+      return !declaringClassName.contains(StringHelper.DOT);
+    }
+    return declaringClassName.startsWith(basePackage + StringHelper.DOT);
   }
 
   /**
-   * Returns a component instance for the specified component class.
+   * Resolves the base package used for compiled-definition scope filtering.
    *
-   * @param componentClass the class declaring annotated MCP component methods
-   * @return the component instance to invoke
+   * <p>Resolution priority:
+   *
+   * <ol>
+   *   <li>{@link McpServerApplication#basePackageClass()} when explicitly configured
+   *   <li>{@link McpServerApplication#basePackage()} when non-blank
+   *   <li>{@code mainClass.getPackageName()} as fallback
+   * </ol>
+   *
+   * @param mainClass application entry class
+   * @return resolved base package (never {@code null})
    */
-  public Object getComponentInstance(Class<?> componentClass) {
-    return componentInstanceFactory.getInstance(componentClass);
+  private static String resolveBasePackage(Class<?> mainClass) {
+    McpServerApplication application = mainClass.getAnnotation(McpServerApplication.class);
+    if (application == null) {
+      return mainClass.getPackageName();
+    }
+
+    if (application.basePackageClass() != Object.class) {
+      return application.basePackageClass().getPackageName();
+    }
+
+    final String configuredBasePackage = application.basePackage().trim();
+    return configuredBasePackage.isBlank() ? mainClass.getPackageName() : configuredBasePackage;
+  }
+
+  /**
+   * Creates a component instance using the class no-argument constructor.
+   *
+   * <p>This method is used by the context cache on first access for each component class.
+   *
+   * @param clazz component class declaring MCP annotated methods
+   * @return created component instance
+   * @throws McpServerException when instance creation fails
+   */
+  private static Object createInstance(Class<?> clazz) {
+    try {
+      return clazz.getDeclaredConstructor().newInstance();
+    } catch (Exception e) {
+      throw new McpServerException(
+          McpServerError.COMPONENT_INSTANCE_CREATE_ERROR.withDetail(clazz.getName()), e);
+    }
   }
 }

src/main/java/com/github/thought2code/mcp/annotated/compiled/completion/CompiledCompletionDefinition.java

@@ -0,0 +1,14 @@
+package com.github.thought2code.mcp.annotated.compiled.completion;
+
+import io.modelcontextprotocol.spec.McpSchema;
+
+/**
+ * Build-time compiled MCP completion definition.
+ *
+ * @param sourceMethod source method descriptor used for diagnostics
+ * @param reference MCP completion reference
+ * @param invoker generated completion invoker
+ */
+public record CompiledCompletionDefinition(
+    String sourceMethod, McpSchema.CompleteReference reference, CompiledCompletionInvoker invoker) {
+}

src/main/java/com/github/thought2code/mcp/annotated/compiled/completion/CompiledCompletionInvoker.java

@@ -0,0 +1,19 @@
+package com.github.thought2code.mcp.annotated.compiled.completion;
+
+import com.github.thought2code.mcp.annotated.McpApplicationContext;
+import com.github.thought2code.mcp.annotated.reflect.Invocation;
+import io.modelcontextprotocol.spec.McpSchema;
+
+/** Strongly-typed invocation contract generated at build time for one completion method. */
+@FunctionalInterface
+public interface CompiledCompletionInvoker {
+  /**
+   * Invokes one compiled completion method.
+   *
+   * @param context application context
+   * @param argument completion argument from request
+   * @return invocation result
+   */
+  Invocation invoke(
+      McpApplicationContext context, McpSchema.CompleteRequest.CompleteArgument argument);
+}

src/main/java/com/github/thought2code/mcp/annotated/compiled/completion/CompiledCompletionSupport.java

@@ -0,0 +1,86 @@
+package com.github.thought2code.mcp.annotated.compiled.completion;
+
+import com.github.thought2code.mcp.annotated.McpApplicationContext;
+import com.github.thought2code.mcp.annotated.compiled.spi.McpCompiledModelProvider;
+import com.github.thought2code.mcp.annotated.exception.McpServerComponentRegistrationException;
+import com.github.thought2code.mcp.annotated.server.component.McpCompleteCompletion;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.spec.McpSchema;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.ServiceLoader;
+import reactor.core.publisher.Mono;
+
+/** Builds completion specifications from build-time compiled completion models. */
+public final class CompiledCompletionSupport {
+
+  private CompiledCompletionSupport() {}
+
+  public static List<McpServerFeatures.SyncCompletionSpecification> allSync(
+      McpApplicationContext context) {
+    return allSync(context, ServiceLoader.load(McpCompiledModelProvider.class));
+  }
+
+  static List<McpServerFeatures.SyncCompletionSpecification> allSync(
+      McpApplicationContext context, Iterable<McpCompiledModelProvider> providers) {
+    List<CompiledCompletionDefinition> definitions = loadDefinitions(providers, context);
+    List<McpServerFeatures.SyncCompletionSpecification> completions = new ArrayList<>();
+    for (CompiledCompletionDefinition definition : definitions) {
+      completions.add(
+          new McpServerFeatures.SyncCompletionSpecification(
+              definition.reference(), (exchange, request) -> invoke(definition, context, request)));
+    }
+    return completions;
+  }
+
+  public static List<McpServerFeatures.AsyncCompletionSpecification> allAsync(
+      McpApplicationContext context) {
+    return allAsync(context, ServiceLoader.load(McpCompiledModelProvider.class));
+  }
+
+  static List<McpServerFeatures.AsyncCompletionSpecification> allAsync(
+      McpApplicationContext context, Iterable<McpCompiledModelProvider> providers) {
+    List<CompiledCompletionDefinition> definitions = loadDefinitions(providers, context);
+    List<McpServerFeatures.AsyncCompletionSpecification> completions = new ArrayList<>();
+    for (CompiledCompletionDefinition definition : definitions) {
+      completions.add(
+          new McpServerFeatures.AsyncCompletionSpecification(
+              definition.reference(),
+              (exchange, request) ->
+                  Mono.fromCallable(() -> invoke(definition, context, request))));
+    }
+    return completions;
+  }
+
+  private static List<CompiledCompletionDefinition> loadDefinitions(
+      Iterable<McpCompiledModelProvider> providers, McpApplicationContext context) {
+    List<CompiledCompletionDefinition> definitions = new ArrayList<>();
+    for (McpCompiledModelProvider provider : providers) {
+      for (CompiledCompletionDefinition definition : provider.completions()) {
+        if (context.isInScope(definition.sourceMethod())) {
+          definitions.add(definition);
+        }
+      }
+    }
+    return definitions;
+  }
+
+  private static McpSchema.CompleteResult invoke(
+      CompiledCompletionDefinition definition,
+      McpApplicationContext context,
+      McpSchema.CompleteRequest request) {
+    var invocation = definition.invoker().invoke(context, request.argument());
+    if (invocation.isError()) {
+      throw new McpServerComponentRegistrationException(
+          "Completion invocation failed for " + definition.sourceMethod());
+    }
+    Object raw = invocation.result();
+    if (!(raw instanceof McpCompleteCompletion completion)) {
+      throw new McpServerComponentRegistrationException(
+          "Completion method must return McpCompleteCompletion: " + definition.sourceMethod());
+    }
+    return new McpSchema.CompleteResult(
+        new McpSchema.CompleteResult.CompleteCompletion(
+            completion.values(), completion.total(), completion.hasMore()));
+  }
+}

src/main/java/com/github/thought2code/mcp/annotated/compiled/prompt/CompiledPromptDefinition.java

@@ -0,0 +1,19 @@
+package com.github.thought2code.mcp.annotated.compiled.prompt;
+
+import io.modelcontextprotocol.spec.McpSchema;
+
+/**
+ * Build-time compiled MCP prompt definition.
+ *
+ * @param sourceMethod source method descriptor used for diagnostics
+ * @param prompt MCP prompt metadata
+ * @param description resolved prompt description
+ * @param invoker generated prompt invoker
+ */
+public record CompiledPromptDefinition(
+    String sourceMethod,
+    McpSchema.Prompt prompt,
+    String description,
+    CompiledPromptInvoker invoker) {
+
+}

src/main/java/com/github/thought2code/mcp/annotated/compiled/prompt/CompiledPromptInvoker.java

@@ -0,0 +1,18 @@
+package com.github.thought2code.mcp.annotated.compiled.prompt;
+
+import com.github.thought2code.mcp.annotated.McpApplicationContext;
+import com.github.thought2code.mcp.annotated.reflect.Invocation;
+import java.util.Map;
+
+/** Strongly-typed invocation contract generated at build time for one {@code @McpPrompt} method. */
+@FunctionalInterface
+public interface CompiledPromptInvoker {
+  /**
+   * Invokes one compiled prompt method using request arguments.
+   *
+   * @param context application context
+   * @param arguments request arguments
+   * @return invocation result
+   */
+  Invocation invoke(McpApplicationContext context, Map<String, Object> arguments);
+}