giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-java/skills/spring-ai-mcp-server-patterns
spring-ai-mcp-server-patterns
VerifiedProvides Spring Boot MCP server patterns that create Model Context Protocol servers with Spring AI by defining tool handlers, exposing resources, configuring prompt templates, and setting up transports for AI function calling and tool calling. Use when building MCP servers to extend AI capabilities with Spring's official AI framework, implementing AI tools, custom function calling, or MCP client integration.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.4 KB |
| references/advanced-patterns.md | markdown | 10.6 KB |
| references/api-reference.md | markdown | 35.8 KB |
| references/examples.md | markdown | 58.5 KB |
| references/implementation-patterns.md | markdown | 11.1 KB |
| references/migration-guide.md | markdown | 4.4 KB |
| references/templates/tool-template.java | other | 11.6 KB |
| references/testing-guide.md | markdown | 7.6 KB |
references/testing-guide.md
View on GitHub# Spring AI MCP Server — Testing Guide
Testing strategies for MCP servers: unit tests, integration tests, Testcontainers, security tests, and slice tests.
## Unit Testing Tools
```java
@SpringBootTest
class DatabaseToolsTest {
@Autowired
private DatabaseTools databaseTools;
@MockBean
private JdbcTemplate jdbcTemplate;
@Test
void testExecuteQuery_Success() {
String query = "SELECT * FROM users WHERE id = ?";
Map<String, Object> params = Map.of("id", 1);
List<Map<String, Object>> expected = List.of(Map.of("id", 1, "name", "John"));
when(jdbcTemplate.queryForList(anyString(), anyMap())).thenReturn(expected);
List<Map<String, Object>> results = databaseTools.executeQuery(query, params);
assertThat(results).isEqualTo(expected);
verify(jdbcTemplate).queryForList(query, params);
}
@Test
void testExecuteQuery_InvalidQuery_ThrowsException() {
String query = "DROP TABLE users";
assertThatThrownBy(() -> databaseTools.executeQuery(query, null))
.isInstanceOf(IllegalArgumentException.class)
.hasMessage("Only SELECT queries are allowed");
verifyNoInteractions(jdbcTemplate);
}
@Test
void testGetTableSchema_Success() {
String tableName = "users";
List<Map<String, Object>> columns = List.of(
Map.of("column_name", "id", "data_type", "integer"),
Map.of("column_name", "name", "data_type", "varchar")
);
when(jdbcTemplate.queryForList(anyString(), eq(tableName))).thenReturn(columns);
TableSchema schema = databaseTools.getTableSchema(tableName);
assertThat(schema.tableName()).isEqualTo(tableName);
assertThat(schema.columns()).isEqualTo(columns);
}
}
```
## Integration Testing
```java
@SpringBootTest
@AutoConfigureMockMvc
class McpServerIntegrationTest {
@Autowired
private MockMvc mockMvc;
@MockBean
private DatabaseTools databaseTools;
@Test
void testExecuteTool_Success() throws Exception {
Map<String, Object> args = Map.of("query", "SELECT * FROM users", "params", Map.of());
List<Map<String, Object>> expectedResult = List.of(Map.of("id", 1, "name", "Test User"));
when(databaseTools.executeQuery(anyString(), anyMap())).thenReturn(expectedResult);
mockMvc.perform(post("/mcp/tools/executeQuery")
.contentType(MediaType.APPLICATION_JSON)
.content(new ObjectMapper().writeValueAsString(args)))
.andExpect(status().isOk())
.andExpect(jsonPath("$.result").isArray())
.andExpect(jsonPath("$.result[0].id").value(1));
}
@Test
void testListTools_Success() throws Exception {
mockMvc.perform(get("/mcp/tools"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.tools").isArray());
}
@Test
void testHealthEndpoint() throws Exception {
mockMvc.perform(get("/actuator/health/mcp"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.status").value("UP"));
}
}
```
## Integration Testing with Testcontainers
```java
@SpringBootTest
@Testcontainers
@AutoConfigureMockMvc
class McpServerDatabaseIntegrationTest {
@Container
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
.withDatabaseName("testdb")
.withUsername("test")
.withPassword("test");
@DynamicPropertySource
static void properties(DynamicPropertyRegistry registry) {
registry.add("spring.datasource.url", postgres::getJdbcUrl);
registry.add("spring.datasource.username", postgres::getUsername);
registry.add("spring.datasource.password", postgres::getPassword);
}
@Autowired
private MockMvc mockMvc;
@Test
void testDatabaseToolWithRealDatabase() throws Exception {
Map<String, Object> request = Map.of(
"tool", "executeQuery",
"arguments", Map.of("query", "SELECT current_database(), current_user")
);
mockMvc.perform(post("/mcp/tools/executeQuery")
.contentType(MediaType.APPLICATION_JSON)
.content(new ObjectMapper().writeValueAsString(request)))
.andExpect(status().isOk())
.andExpect(jsonPath("$.success").value(true))
.andExpect(jsonPath("$.data[0].current_database").value("testdb"));
}
}
```
## Slice Test with `@WebMvcTest`
```java
@WebMvcTest(controllers = McpController.class)
class McpControllerSliceTest {
@Autowired
private MockMvc mockMvc;
@MockBean
private McpServer mcpServer;
@MockBean
private ToolRegistry toolRegistry;
@Test
void testListToolsEndpoint() throws Exception {
Tool tool1 = Tool.builder().name("tool1").description("Tool 1").build();
Tool tool2 = Tool.builder().name("tool2").description("Tool 2").build();
when(toolRegistry.listTools()).thenReturn(List.of(tool1, tool2));
mockMvc.perform(get("/mcp/tools"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.tools").isArray())
.andExpect(jsonPath("$.tools.length()").value(2))
.andExpect(jsonPath("$.tools[0].name").value("tool1"));
}
}
```
## Testing Tool Validation
```java
@ExtendWith(MockitoExtension.class)
class ToolValidationTest {
private ToolValidator validator;
@BeforeEach
void setUp() {
McpServerProperties properties = new McpServerProperties();
properties.getTools().getValidation().setMaxArgumentsSize(1000);
validator = new DefaultToolValidator(properties);
}
@Test
void testValidArguments() {
Tool tool = Tool.builder().name("testTool").method(getTestMethod()).build();
Map<String, Object> args = Map.of("param1", "value1", "param2", 123);
assertDoesNotThrow(() -> validator.validateArguments(tool, args));
}
@Test
void testArgumentsTooLarge() {
Tool tool = Tool.builder().name("testTool").build();
Map<String, Object> args = Map.of("largeParam", "x".repeat(2000));
ValidationException exception = assertThrows(
ValidationException.class,
() -> validator.validateArguments(tool, args));
assertThat(exception.getMessage()).contains("Arguments too large");
}
}
```
## Security Testing
```java
@SpringBootTest
@AutoConfigureMockMvc
@WithMockUser(roles = {"USER"})
class McpSecurityTest {
@Autowired
private MockMvc mockMvc;
@Test
void testUserCanAccessRegularTools() throws Exception {
mockMvc.perform(get("/mcp/tools/getWeather"))
.andExpect(status().isOk());
}
@Test
@WithMockUser(roles = {"USER"})
void testUserCannotAccessAdminTools() throws Exception {
mockMvc.perform(get("/mcp/tools/admin/deleteData"))
.andExpect(status().isForbidden());
}
@Test
@WithMockUser(roles = {"ADMIN"})
void testAdminCanAccessAllTools() throws Exception {
mockMvc.perform(get("/mcp/tools/admin/deleteData"))
.andExpect(status().isOk());
}
}
```
## Configuration Properties Testing
```java
@SpringBootTest
@EnableConfigurationProperties(McpServerProperties.class)
class McpPropertiesTest {
@Autowired
private McpServerProperties properties;
@Test
void testDefaultValues() {
assertThat(properties.getServer().getName()).isEqualTo("spring-ai-mcp-server");
assertThat(properties.getTransport().getType()).isEqualTo(TransportType.STDIO);
assertThat(properties.getSecurity().isEnabled()).isFalse();
}
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |