✨ feat(mcp): BuildDwelling write slice | add MCP server tool

Author: MateuszNaKodach

.claude/tasks/0001_introduce_mcp_server.md

@@ -47,9 +47,9 @@ The MCP server will expose the rich domain model through standardized MCP resour
 
 ### 🚀 Phase 1: Proof of Concept (Start Here)
 **Target: `creaturerecruitment/write/builddwelling` slice**
-- [ ] **creaturerecruitment/write/builddwelling**: Build dwelling tools/resources
-- [ ] Test and validate the first slice implementation
-- [ ] Establish patterns and conventions
+- [x] **creaturerecruitment/write/builddwelling**: Build dwelling tools/resources
+- [x] Test and validate the first slice implementation
+- [x] Establish patterns and conventions
 
 ### 📈 Phase 2: Expand Creature Recruitment Context
 - [ ] **creaturerecruitment/write/recruitcreature**: Recruit creature tools/resources  
@@ -181,4 +181,90 @@ Each phase completion should result in:
 - **Documentation** of patterns and conventions
 - **Performance validation** under realistic load
 
-This incremental approach ensures the MCP server integrates seamlessly with the existing domain architecture while providing rich, domain-aware capabilities for external consumers. Starting with a single slice allows us to establish solid foundations and patterns that can be confidently replicated across the entire application.
+This incremental approach ensures the MCP server integrates seamlessly with the existing domain architecture while providing rich, domain-aware capabilities for external consumers. Starting with a single slice allows us to establish solid foundations and patterns that can be confidently replicated across the entire application.
+
+## 📚 Implementation Patterns & Documentation
+
+### MCP Tool Implementation Pattern
+
+Based on the successful implementation of `build_dwelling` tool, here's the established pattern for creating MCP tools:
+
+#### 1. **File Location**
+- Each slice gets its own `ModelContextProtocol.java` file
+- Location: `{context}/write/{slice}/ModelContextProtocol.java`
+- Example: `creaturerecruitment/write/builddwelling/ModelContextProtocol.java`
+
+#### 2. **Class Structure**
+```java
+@Component
+public class ModelContextProtocol {
+    
+    private final CommandGateway commandGateway;
+    
+    public ModelContextProtocol(CommandGateway commandGateway) {
+        this.commandGateway = commandGateway;
+    }
+    
+    @Tool(
+        name = "tool_name",
+        description = "Detailed description of what the tool does"
+    )
+    public CompletableFuture<Map<String, Object>> methodName(
+        @ToolParam(description = "Parameter description") String param1,
+        // ... more parameters
+    ) {
+        // Implementation
+    }
+}
+```
+
+#### 3. **Key Design Decisions**
+- **Use Spring AI `@Tool`** annotation (not `@McpTool`)
+- **Return `CompletableFuture<Map<String, Object>>`** for async operation results
+- **Include `@ToolParam` descriptions** for all parameters to help AI understand usage
+- **Reuse existing Command/CommandGateway** infrastructure
+- **Follow GameMetaData pattern** for context (gameId, playerId)
+- **Provide structured success/error responses** with consistent format
+
+#### 4. **Parameter Validation Pattern**
+```java
+@ToolParam(description = "Unique identifier for the game instance") String gameId,
+@ToolParam(description = "Unique identifier for the player") String playerId,
+@ToolParam(description = "Unique identifier for the dwelling to build") String dwellingId,
+@ToolParam(description = "Type of creature this dwelling will recruit (e.g., 'ANGEL', 'DRAGON', 'GRIFFIN')") String creatureId,
+@ToolParam(description = "Resource cost per troop recruitment. Map of resource types to amounts (e.g., {'GOLD': 1000, 'WOOD': 10})") Map<String, Integer> costPerTroop
+```
+
+#### 5. **Response Pattern**
+```java
+// Success Response
+return commandGateway.send(command, GameMetaData.with(gameId, playerId))
+    .thenApply(result -> Map.of(
+        "success", true,
+        "dwellingId", dwellingId,
+        "creatureId", creatureId,
+        "costPerTroop", costPerTroop,
+        "message", "Dwelling built successfully"
+    ))
+    .exceptionally(throwable -> Map.of(
+        "success", false,
+        "error", throwable.getMessage(),
+        "dwellingId", dwellingId,
+        "message", "Failed to build dwelling: " + throwable.getMessage()
+    ));
+```
+
+### Next Implementation Steps
+
+With the proven pattern established, implement remaining tools following the same structure:
+
+1. **creaturerecruitment/write/recruitcreature/ModelContextProtocol.java**
+2. **creaturerecruitment/write/changeavailablecreatures/ModelContextProtocol.java** 
+3. **creaturerecruitment/read/getdwellingbyid/ModelContextProtocol.java** (Resources)
+4. **creaturerecruitment/read/getalldwellings/ModelContextProtocol.java** (Resources)
+
+Each implementation should:
+- Follow the established class structure
+- Use appropriate parameter validation
+- Maintain consistent response formats
+- Leverage existing domain infrastructure

src/main/java/com/dddheroes/heroesofddd/ModelContextProtocolConfiguration.java

@@ -0,0 +1,16 @@
+package com.dddheroes.heroesofddd;
+
+import com.dddheroes.heroesofddd.shared.mcp.configuration.HealthCheckMcpTool;
+import org.springframework.ai.tool.ToolCallbackProvider;
+import org.springframework.ai.tool.method.MethodToolCallbackProvider;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class ModelContextProtocolConfiguration {
+
+    @Bean
+    ToolCallbackProvider tools(HealthCheckMcpTool healthCheckMcpTool) {
+        return MethodToolCallbackProvider.builder().toolObjects(healthCheckMcpTool).build();
+    }
+}

src/main/java/com/dddheroes/heroesofddd/creaturerecruitment/write/builddwelling/ModelContextProtocol.java

@@ -0,0 +1,75 @@
+package com.dddheroes.heroesofddd.creaturerecruitment.write.builddwelling;
+
+import com.dddheroes.heroesofddd.shared.application.GameMetaData;
+import org.axonframework.commandhandling.gateway.CommandGateway;
+import org.springframework.ai.chat.model.ToolContext;
+import org.springframework.ai.tool.ToolCallbackProvider;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+import org.springframework.ai.tool.method.MethodToolCallbackProvider;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.stereotype.Component;
+
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+
+public class ModelContextProtocol {
+
+    @Component
+    static class Tools {
+
+        private final CommandGateway commandGateway;
+
+        public Tools(CommandGateway commandGateway) {
+            this.commandGateway = commandGateway;
+        }
+
+        @Tool(
+                name = "build_dwelling",
+                description = "Build a creature dwelling for recruiting specific creatures. Establishes a new dwelling with associated creature type and recruitment cost. The playerId should be provided via MCP client context (similar to REST API headers)."
+        )
+        public CompletableFuture<Map<String, Object>> buildDwelling(
+                @ToolParam(description = "Unique identifier for the game instance") String gameId,
+                @ToolParam(description = "Unique identifier for the dwelling to build") String dwellingId,
+                @ToolParam(description = "Type of creature this dwelling will recruit (e.g., 'ANGEL', 'DRAGON', 'GRIFFIN')") String creatureId,
+                @ToolParam(description = "Resource cost per troop recruitment. Map of resource types to amounts (e.g., {'GOLD': 1000, 'WOOD': 10})") Map<String, Integer> costPerTroop,
+                ToolContext toolContext
+        ) {
+            var playerId = playerId(toolContext);
+
+            var command = BuildDwelling.command(dwellingId, creatureId, costPerTroop);
+
+            return commandGateway.send(command, GameMetaData.with(gameId, playerId))
+                    .thenApply(_ -> Map.of(
+                            "success", true,
+                            "dwellingId", dwellingId,
+                            "creatureId", creatureId,
+                            "costPerTroop", costPerTroop,
+                            "playerId", playerId,
+                            "message", "Dwelling built successfully"
+                    ))
+                    .exceptionally(throwable -> Map.of(
+                            "success", false,
+                            "error", throwable != null ? throwable.getMessage() : "Unknown error",
+                            "dwellingId", dwellingId,
+                            "message", "Failed to build dwelling: " + (throwable != null ? throwable.getMessage() : "Unknown error")
+                    ));
+        }
+
+        private String playerId(ToolContext toolContext) {
+            return (String) toolContext.getContext().getOrDefault("playerId", "default-player-id");
+        }
+
+    }
+
+    @Configuration
+    static class Config {
+
+        @Bean
+        ToolCallbackProvider buildDwellingTool(ModelContextProtocol.Tools sliceTools) {
+            return MethodToolCallbackProvider.builder().toolObjects(sliceTools).build();
+        }
+
+    }
+}

…ed/mcp/configuration/McpHealthCheck.java …cp/configuration/HealthCheckMcpTool.javasrc/main/java/com/dddheroes/heroesofddd/shared/mcp/configuration/McpHealthCheck.java renamed to src/main/java/com/dddheroes/heroesofddd/shared/mcp/configuration/HealthCheckMcpTool.java src/main/java/com/dddheroes/heroesofddd/shared/mcp/configuration/McpHealthCheck.java renamed to src/main/java/com/dddheroes/heroesofddd/shared/mcp/configuration/HealthCheckMcpTool.java

@@ -1,15 +1,15 @@
 package com.dddheroes.heroesofddd.shared.mcp.configuration;
 
-import org.springframework.ai.mcp.server.annotation.McpTool;
+import org.springframework.ai.tool.annotation.Tool;
 import org.springframework.stereotype.Component;
 
 import java.time.LocalDateTime;
 import java.util.Map;
 
 @Component
-public class McpHealthCheck {
+public class HealthCheckMcpTool {
 
-    @McpTool(name = "health_check", description = "Verifies that the MCP server is running and operational")
+    @Tool(name = "health_check", description = "Verifies that the MCP server is running and operational")
     public Map<String, Object> healthCheck() {
         return Map.of(
             "status", "healthy",

src/main/java/com/dddheroes/heroesofddd/shared/mcp/configuration/McpServerConfiguration.java

@@ -1,3 +1,5 @@
+server:
+  port: 3773
 spring:
   application:
     name: heroesofddd
@@ -10,14 +12,7 @@ spring:
         enabled: true
         name: "Heroes of Might & Magic III - DDD/Event Sourcing Server"
         version: "1.0.0"
-        type: SYNC
         instructions: "MCP server for Heroes of Might & Magic III domain built with DDD, Event Sourcing, and Axon Framework. Provides domain operations, game management tools, and educational DDD resources."
-        sse-message-endpoint: /mcp/messages
-        capabilities:
-          tool: true
-          resource: true
-          prompt: true
-          completion: true
   datasource:
     url: jdbc:postgresql://localhost:6446/heroes_of_ddd_development
     username: heroes_of_ddd_db_user