feat: Add annotation-based configuration support for MCP clients and servers

.gitignore

@@ -50,3 +50,5 @@ CLAUDE.md
 qodana.yaml
 __pycache__/
 *.pyc
+
+/contributing

auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/pom.xml

@@ -35,11 +35,12 @@
 			<optional>true</optional>
 		</dependency>
 
-		<!-- <dependency>
-			<groupId>io.modelcontextprotocol.sdk</groupId>
-			<artifactId>mcp-spring-webflux</artifactId>
+		<dependency>
+			<groupId>org.springframework.ai</groupId>
+			<artifactId>spring-ai-mcp-annotations</artifactId>
+			<version>${project.parent.version}</version>
 			<optional>true</optional>
-		</dependency> -->
+		</dependency>
 
 		<dependency>
 			<groupId>org.springframework.boot</groupId>

auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/McpClientAutoConfiguration.java

@@ -23,7 +23,23 @@
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.McpSyncClient;
 import io.modelcontextprotocol.spec.McpSchema;
-
+import org.springaicommunity.mcp.method.changed.prompt.AsyncPromptListChangedSpecification;
+import org.springaicommunity.mcp.method.changed.prompt.SyncPromptListChangedSpecification;
+import org.springaicommunity.mcp.method.changed.resource.AsyncResourceListChangedSpecification;
+import org.springaicommunity.mcp.method.changed.resource.SyncResourceListChangedSpecification;
+import org.springaicommunity.mcp.method.changed.tool.AsyncToolListChangedSpecification;
+import org.springaicommunity.mcp.method.changed.tool.SyncToolListChangedSpecification;
+import org.springaicommunity.mcp.method.elicitation.AsyncElicitationSpecification;
+import org.springaicommunity.mcp.method.elicitation.SyncElicitationSpecification;
+import org.springaicommunity.mcp.method.logging.AsyncLoggingSpecification;
+import org.springaicommunity.mcp.method.logging.SyncLoggingSpecification;
+import org.springaicommunity.mcp.method.progress.AsyncProgressSpecification;
+import org.springaicommunity.mcp.method.progress.SyncProgressSpecification;
+import org.springaicommunity.mcp.method.sampling.AsyncSamplingSpecification;
+import org.springaicommunity.mcp.method.sampling.SyncSamplingSpecification;
+
+import org.springframework.ai.mcp.client.common.autoconfigure.annotations.McpAsyncAnnotationCustomizer;
+import org.springframework.ai.mcp.client.common.autoconfigure.annotations.McpSyncAnnotationCustomizer;
 import org.springframework.ai.mcp.client.common.autoconfigure.configurer.McpAsyncClientConfigurer;
 import org.springframework.ai.mcp.client.common.autoconfigure.configurer.McpSyncClientConfigurer;
 import org.springframework.ai.mcp.client.common.autoconfigure.properties.McpClientCommonProperties;
@@ -95,8 +111,6 @@
  * @see McpSyncClientCustomizer
  * @see McpAsyncClientCustomizer
  * @see StdioTransportAutoConfiguration
- * @see SseHttpClientTransportAutoConfiguration
- * @see SseWebFluxTransportAutoConfiguration
  */
 @AutoConfiguration(afterName = {
 		"org.springframework.ai.mcp.client.common.autoconfigure.StdioTransportAutoConfiguration",
@@ -208,6 +222,20 @@ McpSyncClientConfigurer mcpSyncClientConfigurer(ObjectProvider<McpSyncClientCust
 		return new McpSyncClientConfigurer(customizerProvider.orderedStream().toList());
 	}
 
+	@Bean
+	@ConditionalOnProperty(prefix = McpClientCommonProperties.CONFIG_PREFIX, name = "type", havingValue = "SYNC",
+			matchIfMissing = true)
+	public McpSyncClientCustomizer mcpAnnotationMcpSyncClientCustomizer(List<SyncLoggingSpecification> loggingSpecs,
+			List<SyncSamplingSpecification> samplingSpecs, List<SyncElicitationSpecification> elicitationSpecs,
+			List<SyncProgressSpecification> progressSpecs,
+			List<SyncToolListChangedSpecification> syncToolListChangedSpecifications,
+			List<SyncResourceListChangedSpecification> syncResourceListChangedSpecifications,
+			List<SyncPromptListChangedSpecification> syncPromptListChangedSpecifications) {
+		return new McpSyncAnnotationCustomizer(samplingSpecs, loggingSpecs, elicitationSpecs, progressSpecs,
+				syncToolListChangedSpecifications, syncResourceListChangedSpecifications,
+				syncPromptListChangedSpecifications);
+	}
+
 	// Async client configuration
 
 	@Bean
@@ -259,6 +287,18 @@ McpAsyncClientConfigurer mcpAsyncClientConfigurer(ObjectProvider<McpAsyncClientC
 		return new McpAsyncClientConfigurer(customizerProvider.orderedStream().toList());
 	}
 
+	@Bean
+	@ConditionalOnProperty(prefix = McpClientCommonProperties.CONFIG_PREFIX, name = "type", havingValue = "ASYNC")
+	public McpAsyncClientCustomizer mcpAnnotationMcpAsyncClientCustomizer(List<AsyncLoggingSpecification> loggingSpecs,
+			List<AsyncSamplingSpecification> samplingSpecs, List<AsyncElicitationSpecification> elicitationSpecs,
+			List<AsyncProgressSpecification> progressSpecs,
+			List<AsyncToolListChangedSpecification> toolListChangedSpecs,
+			List<AsyncResourceListChangedSpecification> resourceListChangedSpecs,
+			List<AsyncPromptListChangedSpecification> promptListChangedSpecs) {
+		return new McpAsyncAnnotationCustomizer(samplingSpecs, loggingSpecs, elicitationSpecs, progressSpecs,
+				toolListChangedSpecs, resourceListChangedSpecs, promptListChangedSpecs);
+	}
+
 	/**
 	 * Record class that implements {@link AutoCloseable} to ensure proper cleanup of MCP
 	 * clients.

auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/annotations/ClientAnnotationScannerAutoConfiguration.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.mcp.client.common.autoconfigure.annotations;
+
+import java.lang.annotation.Annotation;
+import java.util.Set;
+
+import org.springaicommunity.mcp.annotation.McpElicitation;
+import org.springaicommunity.mcp.annotation.McpLogging;
+import org.springaicommunity.mcp.annotation.McpProgress;
+import org.springaicommunity.mcp.annotation.McpSampling;
+
+import org.springframework.ai.mcp.annotation.spring.scan.AbstractAnnotatedMethodBeanPostProcessor;
+import org.springframework.ai.mcp.annotation.spring.scan.AbstractMcpAnnotatedBeans;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * @author Christian Tzolov
+ */
+@AutoConfiguration
+@ConditionalOnProperty(prefix = ClientAnnotationScannerProperties.CONFIG_PREFIX, name = "enabled", havingValue = "true",
+		matchIfMissing = true)
+@EnableConfigurationProperties(ClientAnnotationScannerProperties.class)
+public class ClientAnnotationScannerAutoConfiguration {
+
+	private static final Set<Class<? extends Annotation>> CLIENT_MCP_ANNOTATIONS = Set.of(McpLogging.class,
+			McpSampling.class, McpElicitation.class, McpProgress.class);
+
+	@Bean
+	@ConditionalOnMissingBean
+	public ClientMcpAnnotatedBeans clientAnnotatedBeans() {
+		return new ClientMcpAnnotatedBeans();
+	}
+
+	@Bean
+	@ConditionalOnMissingBean
+	public ClientAnnotatedMethodBeanPostProcessor clientAnnotatedMethodBeanPostProcessor(
+			ClientMcpAnnotatedBeans clientMcpAnnotatedBeans, ClientAnnotationScannerProperties properties) {
+		return new ClientAnnotatedMethodBeanPostProcessor(clientMcpAnnotatedBeans, CLIENT_MCP_ANNOTATIONS);
+	}
+
+	public static class ClientMcpAnnotatedBeans extends AbstractMcpAnnotatedBeans {
+
+	}
+
+	public static class ClientAnnotatedMethodBeanPostProcessor extends AbstractAnnotatedMethodBeanPostProcessor {
+
+		public ClientAnnotatedMethodBeanPostProcessor(ClientMcpAnnotatedBeans clientMcpAnnotatedBeans,
+				Set<Class<? extends Annotation>> targetAnnotations) {
+			super(clientMcpAnnotatedBeans, targetAnnotations);
+		}
+
+	}
+
+}

auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/annotations/ClientAnnotationScannerProperties.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.mcp.client.common.autoconfigure.annotations;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/**
+ * @author Christian Tzolov
+ */
+@ConfigurationProperties(prefix = ClientAnnotationScannerProperties.CONFIG_PREFIX)
+public class ClientAnnotationScannerProperties {
+
+	public static final String CONFIG_PREFIX = "spring.ai.mcp.client.annotation-scanner";
+
+	private boolean enabled = true;
+
+	public boolean isEnabled() {
+		return this.enabled;
+	}
+
+	public void setEnabled(boolean enabled) {
+		this.enabled = enabled;
+	}
+
+}

auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/annotations/ClientSpecificationFactoryAutoConfiguration.java

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.mcp.client.common.autoconfigure.annotations;
+
+import java.util.List;
+
+import org.springaicommunity.mcp.annotation.McpElicitation;
+import org.springaicommunity.mcp.annotation.McpLogging;
+import org.springaicommunity.mcp.annotation.McpProgress;
+import org.springaicommunity.mcp.annotation.McpSampling;
+import org.springaicommunity.mcp.method.elicitation.AsyncElicitationSpecification;
+import org.springaicommunity.mcp.method.elicitation.SyncElicitationSpecification;
+import org.springaicommunity.mcp.method.logging.AsyncLoggingSpecification;
+import org.springaicommunity.mcp.method.logging.SyncLoggingSpecification;
+import org.springaicommunity.mcp.method.progress.AsyncProgressSpecification;
+import org.springaicommunity.mcp.method.progress.SyncProgressSpecification;
+import org.springaicommunity.mcp.method.sampling.AsyncSamplingSpecification;
+import org.springaicommunity.mcp.method.sampling.SyncSamplingSpecification;
+
+import org.springframework.ai.mcp.annotation.spring.AsyncMcpAnnotationProviders;
+import org.springframework.ai.mcp.annotation.spring.SyncMcpAnnotationProviders;
+import org.springframework.ai.mcp.client.common.autoconfigure.annotations.ClientAnnotationScannerAutoConfiguration.ClientMcpAnnotatedBeans;
+import org.springframework.ai.mcp.client.common.autoconfigure.properties.McpClientCommonProperties;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * @author Christian Tzolov
+ */
+@AutoConfiguration(after = ClientAnnotationScannerAutoConfiguration.class)
+@ConditionalOnProperty(prefix = ClientAnnotationScannerProperties.CONFIG_PREFIX, name = "enabled", havingValue = "true",
+		matchIfMissing = true)
+public class ClientSpecificationFactoryAutoConfiguration {
+
+	@Configuration(proxyBeanMethods = false)
+	@ConditionalOnProperty(prefix = McpClientCommonProperties.CONFIG_PREFIX, name = "type", havingValue = "SYNC",
+			matchIfMissing = true)
+	static class SyncClientSpecificationConfiguration {
+
+		@Bean
+		List<SyncLoggingSpecification> loggingSpecs(ClientMcpAnnotatedBeans beansWithMcpMethodAnnotations) {
+			return SyncMcpAnnotationProviders
+				.loggingSpecifications(beansWithMcpMethodAnnotations.getBeansByAnnotation(McpLogging.class));
+		}
+
+		@Bean
+		List<SyncSamplingSpecification> samplingSpecs(ClientMcpAnnotatedBeans beansWithMcpMethodAnnotations) {
+			return SyncMcpAnnotationProviders
+				.samplingSpecifications(beansWithMcpMethodAnnotations.getBeansByAnnotation(McpSampling.class));
+		}
+
+		@Bean
+		List<SyncElicitationSpecification> elicitationSpecs(ClientMcpAnnotatedBeans beansWithMcpMethodAnnotations) {
+			return SyncMcpAnnotationProviders
+				.elicitationSpecifications(beansWithMcpMethodAnnotations.getBeansByAnnotation(McpElicitation.class));
+		}
+
+		@Bean
+		List<SyncProgressSpecification> progressSpecs(ClientMcpAnnotatedBeans beansWithMcpMethodAnnotations) {
+			return SyncMcpAnnotationProviders
+				.progressSpecifications(beansWithMcpMethodAnnotations.getBeansByAnnotation(McpProgress.class));
+		}
+
+	}
+
+	@Configuration(proxyBeanMethods = false)
+	@ConditionalOnProperty(prefix = McpClientCommonProperties.CONFIG_PREFIX, name = "type", havingValue = "ASYNC")
+	static class AsyncClientSpecificationConfiguration {
+
+		@Bean
+		List<AsyncLoggingSpecification> loggingSpecs(ClientMcpAnnotatedBeans beanRegistry) {
+			return AsyncMcpAnnotationProviders.loggingSpecifications(beanRegistry.getAllAnnotatedBeans());
+		}
+
+		@Bean
+		List<AsyncSamplingSpecification> samplingSpecs(ClientMcpAnnotatedBeans beanRegistry) {
+			return AsyncMcpAnnotationProviders.samplingSpecifications(beanRegistry.getAllAnnotatedBeans());
+		}
+
+		@Bean
+		List<AsyncElicitationSpecification> elicitationSpecs(ClientMcpAnnotatedBeans beanRegistry) {
+			return AsyncMcpAnnotationProviders.elicitationSpecifications(beanRegistry.getAllAnnotatedBeans());
+		}
+
+		@Bean
+		List<AsyncProgressSpecification> progressSpecs(ClientMcpAnnotatedBeans beanRegistry) {
+			return AsyncMcpAnnotationProviders.progressSpecifications(beanRegistry.getAllAnnotatedBeans());
+		}
+
+	}
+
+}