Skip to content

Commit fc77dce

Browse files
MateuszNaKodachMateuszNaKodach
committed
🤖 ai-agent(claude-code): MCP - planning the MCP server introduction
1 parent 720f4ac commit fc77dce

2 files changed

Lines changed: 293 additions & 0 deletions

File tree

‎.claude/commands/execute-task.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Execute Task
2+
3+
Execute implementation tasks from `./.claude/tasks/` directory with adaptive planning and iterative execution.
4+
Execute a just task which is in $ARGUMENTS.
5+
6+
## Usage
7+
8+
```bash
9+
claude execute-task <task-name>
10+
```
11+
12+
**Arguments:**
13+
- `<task-name>` (required): Name of the task file in `./.claude/tasks/` directory (without .md extension)
14+
15+
**Examples:**
16+
```bash
17+
claude execute-task mcp-server-implementation-plan
18+
claude execute-task api-refactoring-plan
19+
claude execute-task performance-optimization
20+
```
21+
22+
## Command Description
23+
24+
This command executes task plans from the `.claude/tasks/` directory as a **Senior Software Engineer** proficient in Java, Axon Framework 4, JUnit 5, and AssertJ. The command treats the plan as **inspiration** and adapts it during execution as needed.
25+
26+
### Execution Approach
27+
28+
1. **📋 Plan Analysis**: Read and understand the task plan from the specified file
29+
2. **🎯 Adaptive Planning**: Plan 3 steps ahead based on current context and progress
30+
3. **⚡ Execute**: Implement the 3 planned steps with full code implementation
31+
4. **✅ Review Checkpoint**: Present completed work and ask for human review/adjustments
32+
5. **🔄 Iterate**: Plan next 3 steps based on progress and feedback, then repeat
33+
34+
### Key Behaviors
35+
36+
- **Plan as Inspiration**: Use the task plan as guidance, but adapt based on:
37+
- Current codebase state
38+
- Discovered technical constraints
39+
- Better implementation approaches found during execution
40+
- Human feedback and preferences
41+
42+
- **Progress Tracking**:
43+
- Mark completed checkboxes in the plan file
44+
- Update plan with discovered requirements or changes
45+
- Document decisions and rationale for deviations
46+
47+
- **Senior Engineer Approach**:
48+
- Ask clarifying questions when context is unclear
49+
- Suggest improvements and alternatives
50+
- Follow best practices for Java, Axon Framework 4, JUnit 5, AssertJ
51+
- Ensure code quality, testing, and maintainability
52+
- Respect existing codebase patterns and conventions
53+
54+
- **Human-in-the-Loop**:
55+
- Present completed work after every 3 steps
56+
- Ask for feedback on implementation approach
57+
- Confirm direction before proceeding with next steps
58+
- Suggest plan adjustments when needed
59+
60+
### Example Execution Flow
61+
62+
```
63+
📋 Reading plan from: ./.claude/tasks/mcp-server-implementation-plan.md
64+
🎯 Planning next 3 steps:
65+
1. Add Spring AI MCP Server dependencies to pom.xml
66+
2. Create base MCP configuration in shared/mcp/configuration/
67+
3. Set up authentication/authorization structure
68+
69+
⚡ Executing steps 1-3...
70+
✅ Step 1: Added spring-ai-starter-mcp-server-webmvc dependency
71+
✅ Step 2: Created McpServerConfiguration.java with base setup
72+
✅ Step 3: Implemented McpSecurityConfig.java with authentication
73+
74+
📊 Progress Update: Updated plan file - marked 3 items as completed
75+
76+
🤔 Review needed: I've completed the foundation setup. The MCP server is now configured with basic authentication. I noticed the existing codebase uses custom GameMetaData for request context - should we integrate this with MCP authentication?
77+
78+
Next planned steps:
79+
4. Create ModelContextProtocol.java in creaturerecruitment/write/builddwelling/
80+
5. Implement build dwelling tool using existing BuildDwelling command
81+
6. Add JSON schema generation for BuildDwelling parameters
82+
83+
👤 [Awaiting human feedback before proceeding...]
84+
```
85+
86+
### Questions to Ask
87+
88+
The command will proactively ask questions like:
89+
- "I see the codebase uses [pattern X]. Should I follow the same pattern for MCP implementation?"
90+
- "The existing authentication uses [approach Y]. How should this integrate with MCP security?"
91+
- "I found [technical constraint Z]. Should we adjust the plan to accommodate this?"
92+
- "Would you prefer [implementation option A] or [implementation option B] for [specific feature]?"
93+
94+
### Error Handling
95+
96+
- If the specified task file doesn't exist, list available files in `./.claude/tasks/`
97+
- If a step fails, ask for guidance before proceeding
98+
- If dependencies are missing, suggest adding them and ask for confirmation
99+
- If tests fail, fix them before marking steps as complete
100+
101+
### Plan Updates
102+
103+
The command will update the original plan file with:
104+
- ✅ Completed checkboxes
105+
- 📝 Notes about implementation decisions
106+
- 🔄 Adjusted steps based on discoveries
107+
- 📅 Timestamps for major milestones
108+
109+
This ensures the plan remains a living document that reflects actual implementation progress and decisions.

‎.claude/tasks/0001_introduce_mcp_server.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# MCP Server Implementation Plan
2+
3+
## Context
4+
5+
This task involves implementing an MCP (Model Context Protocol) server for the Heroes of Might & Magic III domain application. The application is built using Domain-Driven Design with Event Sourcing, CQRS, and Vertical Slice Architecture using Axon Framework and Spring Boot.
6+
7+
The MCP server will expose the rich domain model through standardized MCP resources, tools, and prompts, making it valuable for:
8+
- Game development and testing
9+
- DDD/Event Sourcing education
10+
- AI-assisted game strategy analysis
11+
- Domain modeling demonstrations
12+
13+
## Implementation Approach
14+
15+
**🎯 Start Small, Scale Up**: We will begin with a single bounded context (**Creature Recruitment**) and implement one complete slice (`creaturerecruitment/write/builddwelling`) as a proof of concept. Once this foundation is solid, we'll expand to other slices within the same bounded context, then replicate the pattern across other bounded contexts.
16+
17+
## Phase 1: General Plan
18+
19+
### MCP Server Capabilities Overview
20+
21+
**Resources (Read-Only Data Access)**
22+
- Game state resources (dwellings, armies, calendar)
23+
- Domain knowledge schemas (creatures, resources, commands)
24+
- Event streams for analysis and debugging
25+
26+
**Tools (Interactive Operations)**
27+
- Game management (create, day progression)
28+
- Dwelling operations (build, recruit creatures)
29+
- Army management (add/remove creatures)
30+
- Resource management (deposit/withdraw)
31+
- Analysis tools (game state, validation, cost calculation)
32+
33+
**Prompts (Domain Intelligence)**
34+
- Game strategy and planning
35+
- Educational DDD/Event Sourcing concepts
36+
- Testing scenario generation
37+
- Game balance analysis
38+
- Maintenance and debugging
39+
40+
## Phase 2: Implementation TODOs
41+
42+
### 🏗️ Core Infrastructure (Foundation)
43+
- [ ] Add Spring AI MCP Server dependencies
44+
- [ ] Configure MCP server in Spring Boot application
45+
- [ ] Create base MCP configuration classes in `shared/mcp/`
46+
- [ ] Implement authentication/authorization for MCP
47+
48+
### 🚀 Phase 1: Proof of Concept (Start Here)
49+
**Target: `creaturerecruitment/write/builddwelling` slice**
50+
- [ ] **creaturerecruitment/write/builddwelling**: Build dwelling tools/resources
51+
- [ ] Test and validate the first slice implementation
52+
- [ ] Establish patterns and conventions
53+
54+
### 📈 Phase 2: Expand Creature Recruitment Context
55+
- [ ] **creaturerecruitment/write/recruitcreature**: Recruit creature tools/resources
56+
- [ ] **creaturerecruitment/write/changeavailablecreatures**: Availability tools/resources
57+
- [ ] **creaturerecruitment/read/getdwellingbyid**: Single dwelling query resources
58+
- [ ] **creaturerecruitment/read/getalldwellings**: Dwellings list query resources
59+
- [ ] **creaturerecruitment**: Shared recruitment strategy prompts
60+
61+
### 🔄 Phase 3: Replicate to Other Contexts
62+
- [ ] **armies/write/addcreature**: Add creature to army tools
63+
- [ ] **armies/write/removecreature**: Remove creature from army tools
64+
- [ ] **armies**: Army composition and strategy prompts
65+
- [ ] **calendar/write/startday**: Start day progression tools
66+
- [ ] **calendar/write/finishday**: Finish day progression tools
67+
- [ ] **calendar**: Time management and planning prompts
68+
- [ ] **resourcespool/write/deposit**: Resource deposit tools
69+
- [ ] **resourcespool/write/withdraw**: Resource withdrawal tools
70+
- [ ] **resourcespool**: Resource optimization prompts
71+
72+
### 🔧 Phase 4: Advanced Features
73+
- [ ] **maintenance/read/geteventstream**: Event stream query resources
74+
- [ ] **maintenance/write/resetprocessor**: Processor management tools
75+
- [ ] Cross-context analysis prompts
76+
- [ ] Game balance and optimization prompts
77+
- [ ] Educational DDD/Event Sourcing prompts
78+
79+
### ✅ Integration & Testing
80+
- [ ] Integration tests for MCP endpoints
81+
- [ ] Documentation and examples
82+
- [ ] Performance optimization
83+
84+
## Phase 3: Technology Stack
85+
86+
### Core Dependencies
87+
- **Spring Boot** (existing)
88+
- **Spring AI MCP Server**: `spring-ai-starter-mcp-server-webmvc`
89+
- **Axon Framework** (existing - for command/query handling)
90+
- **Spring Data JPA** (existing - for read models)
91+
92+
### MCP-Specific Components
93+
- MCP Resource providers
94+
- MCP Tool handlers
95+
- MCP Prompt processors
96+
- JSON Schema generators for domain objects
97+
98+
## Phase 4: Architecture
99+
100+
### Vertical Slice Architecture Alignment
101+
102+
Each slice will contain its own MCP components in `ModelContextProtocol.java` files:
103+
104+
```
105+
com.dddheroes.heroesofddd/
106+
├── creaturerecruitment/
107+
│ ├── write/
108+
│ │ ├── builddwelling/
109+
│ │ │ └── ModelContextProtocol.java # Build dwelling tools/resources
110+
│ │ ├── recruitcreature/
111+
│ │ │ └── ModelContextProtocol.java # Recruit creature tools/resources
112+
│ │ └── changeavailablecreatures/
113+
│ │ └── ModelContextProtocol.java # Availability management tools
114+
│ ├── read/
115+
│ │ ├── getdwellingbyid/
116+
│ │ │ └── ModelContextProtocol.java # Dwelling query resources
117+
│ │ └── getalldwellings/
118+
│ │ └── ModelContextProtocol.java # Dwellings list resources
119+
│ └── ModelContextProtocol.java # Shared recruitment prompts
120+
├── armies/
121+
│ ├── write/
122+
│ │ ├── addcreature/
123+
│ │ │ └── ModelContextProtocol.java # Add creature tools
124+
│ │ └── removecreature/
125+
│ │ └── ModelContextProtocol.java # Remove creature tools
126+
│ └── ModelContextProtocol.java # Army strategy prompts
127+
├── calendar/
128+
│ ├── write/
129+
│ │ ├── startday/
130+
│ │ │ └── ModelContextProtocol.java # Start day tools
131+
│ │ └── finishday/
132+
│ │ └── ModelContextProtocol.java # Finish day tools
133+
│ └── ModelContextProtocol.java # Time management prompts
134+
├── resourcespool/
135+
│ ├── write/
136+
│ │ ├── deposit/
137+
│ │ │ └── ModelContextProtocol.java # Deposit tools
138+
│ │ └── withdraw/
139+
│ │ └── ModelContextProtocol.java # Withdraw tools
140+
│ └── ModelContextProtocol.java # Resource strategy prompts
141+
├── maintenance/
142+
│ ├── read/geteventstream/
143+
│ │ └── ModelContextProtocol.java # Event stream resources
144+
│ └── write/resetprocessor/
145+
│ └── ModelContextProtocol.java # Processor management tools
146+
└── shared/
147+
└── mcp/
148+
├── configuration/ # Base MCP config
149+
├── schemas/ # Domain schemas
150+
└── security/ # Authentication
151+
```
152+
153+
### MCP Integration Points
154+
- **Resources**: Connect to existing read models and query handlers
155+
- **Tools**: Leverage existing command handlers and REST APIs
156+
- **Prompts**: Use domain services and business logic
157+
- **Security**: Integrate with existing authentication mechanisms
158+
159+
### Design Principles
160+
- Maintain bounded context isolation
161+
- Reuse existing command/query infrastructure
162+
- Follow existing domain patterns
163+
- Ensure event sourcing audit trails
164+
- Preserve business rule validation
165+
166+
## Implementation Strategy
167+
168+
### 🎯 Incremental Development Approach
169+
170+
1. **🏗️ Foundation First**: Establish shared MCP infrastructure and configuration
171+
2. **🚀 Proof of Concept**: Implement single slice (`creaturerecruitment/write/builddwelling`) to validate approach
172+
3. **📈 Context Completion**: Complete all slices within Creature Recruitment bounded context
173+
4. **🔄 Pattern Replication**: Apply proven patterns to other bounded contexts (armies, calendar, etc.)
174+
5. **🔧 Advanced Features**: Add cross-context analysis, educational prompts, and optimization tools
175+
176+
### 🎉 Success Criteria
177+
178+
Each phase completion should result in:
179+
- **Working MCP endpoints** for the implemented slices
180+
- **Comprehensive testing** of tools/resources/prompts
181+
- **Documentation** of patterns and conventions
182+
- **Performance validation** under realistic load
183+
184+
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.

0 commit comments

Comments
 (0)