Clean up
This commit is contained in:
Yaojia Wang
441
docs/plans/sprint_5_story_13.md
Normal file
441
docs/plans/sprint_5_story_13.md
Normal file
@@ -0,0 +1,441 @@
|
||||
---
|
||||
story_id: story_13
|
||||
sprint_id: sprint_5
|
||||
parent_story_id: story_0
|
||||
status: not_started
|
||||
priority: P0
|
||||
assignee: backend
|
||||
created_date: 2025-11-09
|
||||
estimated_days: 10
|
||||
phase: 1
|
||||
---
|
||||
|
||||
# Story 13: MCP SDK Foundation & Proof of Concept
|
||||
|
||||
**Parent Epic**: [Story 0](sprint_5_story_0.md) - Integrate Microsoft .NET MCP SDK
|
||||
**Phase**: 1 - Foundation (Week 1-2)
|
||||
**Priority**: P0 - Critical
|
||||
**Estimated Effort**: 10 days (2 weeks)
|
||||
|
||||
## User Story
|
||||
|
||||
**As** a backend developer,
|
||||
**I want** to install and validate the Microsoft .NET MCP SDK,
|
||||
**So that** we can confidently migrate from custom MCP implementation to the official SDK.
|
||||
|
||||
## Business Value
|
||||
|
||||
- **Risk Mitigation**: Validate SDK compatibility before committing to full migration
|
||||
- **Performance Baseline**: Establish performance metrics for comparison
|
||||
- **Team Readiness**: Train team on SDK APIs and patterns
|
||||
- **Decision Validation**: Confirm hybrid architecture approach is viable
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Microsoft .NET MCP SDK installed from NuGet
|
||||
- [ ] PoC Tool successfully registered using `[McpTool]` attribute
|
||||
- [ ] PoC Resource successfully registered using `[McpResource]` attribute
|
||||
- [ ] PoC validated with Claude Desktop (stdio transport)
|
||||
- [ ] Performance baseline recorded (response time, throughput, memory)
|
||||
- [ ] Compatibility verified with existing Clean Architecture
|
||||
- [ ] Team training completed (2-hour workshop)
|
||||
- [ ] Migration guide document created
|
||||
|
||||
## Technical Scope
|
||||
|
||||
### 1. SDK Installation & Configuration
|
||||
|
||||
**Goal**: Install SDK and configure basic infrastructure
|
||||
|
||||
**Tasks**:
|
||||
1. Add NuGet package reference
|
||||
2. Configure SDK services in DI container
|
||||
3. Setup basic transport (stdio only for PoC)
|
||||
4. Verify SDK initialization
|
||||
|
||||
**Expected Changes**:
|
||||
```csharp
|
||||
// ColaFlow.Modules.Mcp.csproj
|
||||
<PackageReference Include="Microsoft.MCP" Version="1.0.0" />
|
||||
<PackageReference Include="Microsoft.MCP.Server" Version="1.0.0" />
|
||||
```
|
||||
|
||||
```csharp
|
||||
// Program.cs or Startup.cs
|
||||
services.AddMcpServer(options =>
|
||||
{
|
||||
options.UseStdioTransport(); // PoC only
|
||||
options.DiscoverToolsAndResources(); // Auto-discovery
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. PoC Tool Implementation
|
||||
|
||||
**Goal**: Create one Tool using SDK to validate approach
|
||||
|
||||
**PoC Tool**: `ping` (simple echo tool for testing)
|
||||
|
||||
**Implementation**:
|
||||
```csharp
|
||||
// ColaFlow.Modules.Mcp/Tools/PingTool.cs
|
||||
using Microsoft.MCP;
|
||||
|
||||
[McpTool(
|
||||
Name = "ping",
|
||||
Description = "Test tool that echoes back the input message"
|
||||
)]
|
||||
public class PingTool
|
||||
{
|
||||
[McpToolParameter(
|
||||
Name = "message",
|
||||
Description = "Message to echo back",
|
||||
Required = true
|
||||
)]
|
||||
public string Message { get; set; } = string.Empty;
|
||||
|
||||
[McpToolParameter(
|
||||
Name = "delay_ms",
|
||||
Description = "Optional delay in milliseconds",
|
||||
Required = false
|
||||
)]
|
||||
public int? DelayMs { get; set; }
|
||||
|
||||
public async Task<McpToolResult> ExecuteAsync(
|
||||
McpContext context,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
if (DelayMs.HasValue)
|
||||
{
|
||||
await Task.Delay(DelayMs.Value, cancellationToken);
|
||||
}
|
||||
|
||||
return McpToolResult.Success(new
|
||||
{
|
||||
Echo = Message,
|
||||
Timestamp = DateTime.UtcNow,
|
||||
TenantId = context.TenantId, // Verify tenant context works
|
||||
UserId = context.UserId
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Steps**:
|
||||
1. Register tool (automatic via SDK discovery)
|
||||
2. Call tool from Claude Desktop
|
||||
3. Verify response correctness
|
||||
4. Measure performance
|
||||
|
||||
---
|
||||
|
||||
### 3. PoC Resource Implementation
|
||||
|
||||
**Goal**: Create one Resource using SDK to validate approach
|
||||
|
||||
**PoC Resource**: `system.info` (system metadata)
|
||||
|
||||
**Implementation**:
|
||||
```csharp
|
||||
// ColaFlow.Modules.Mcp/Resources/SystemInfoResource.cs
|
||||
using Microsoft.MCP;
|
||||
|
||||
[McpResource(
|
||||
Uri = "colaflow://system.info",
|
||||
Name = "System Information",
|
||||
Description = "Get ColaFlow system metadata and health status",
|
||||
MimeType = "application/json"
|
||||
)]
|
||||
public class SystemInfoResource
|
||||
{
|
||||
private readonly ITenantContext _tenantContext;
|
||||
private readonly IConfiguration _config;
|
||||
|
||||
public SystemInfoResource(
|
||||
ITenantContext tenantContext,
|
||||
IConfiguration config)
|
||||
{
|
||||
_tenantContext = tenantContext;
|
||||
_config = config;
|
||||
}
|
||||
|
||||
public async Task<McpResourceContent> GetContentAsync(
|
||||
McpContext context,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var info = new
|
||||
{
|
||||
Version = "1.0.0",
|
||||
Environment = _config["Environment"],
|
||||
TenantId = _tenantContext.CurrentTenantId,
|
||||
ServerTime = DateTime.UtcNow,
|
||||
Uptime = GetUptime()
|
||||
};
|
||||
|
||||
return McpResourceContent.Json(info);
|
||||
}
|
||||
|
||||
private TimeSpan GetUptime()
|
||||
{
|
||||
return DateTime.UtcNow - Process.GetCurrentProcess().StartTime;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Steps**:
|
||||
1. Register resource (automatic via SDK discovery)
|
||||
2. Query resource from Claude Desktop
|
||||
3. Verify JSON response format
|
||||
4. Verify tenant context isolation
|
||||
|
||||
---
|
||||
|
||||
### 4. Claude Desktop Integration Testing
|
||||
|
||||
**Goal**: Validate SDK works with real MCP client
|
||||
|
||||
**Setup**:
|
||||
1. Configure Claude Desktop MCP client
|
||||
2. Add ColaFlow as MCP server in config
|
||||
3. Test Tool and Resource calls
|
||||
4. Verify error handling
|
||||
|
||||
**Claude Desktop Config** (`claude_desktop_config.json`):
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"colaflow-poc": {
|
||||
"command": "dotnet",
|
||||
"args": ["run", "--project", "ColaFlow.Modules.Mcp"],
|
||||
"env": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Test Cases**:
|
||||
1. **Tool Call**: `ping` with message "Hello MCP SDK"
|
||||
2. **Resource Query**: `colaflow://system.info`
|
||||
3. **Error Handling**: Invalid tool parameters
|
||||
4. **Multi-Tenant**: Verify tenant isolation
|
||||
|
||||
---
|
||||
|
||||
### 5. Performance Baseline Benchmarking
|
||||
|
||||
**Goal**: Establish baseline metrics for comparison
|
||||
|
||||
**Metrics to Measure**:
|
||||
1. **Tool Execution Time** (P50, P95, P99)
|
||||
2. **Resource Query Time** (P50, P95, P99)
|
||||
3. **Memory Usage** (baseline, peak)
|
||||
4. **Throughput** (requests/second)
|
||||
5. **SDK Overhead** (protocol parsing time)
|
||||
|
||||
**Benchmark Tool**: BenchmarkDotNet
|
||||
|
||||
**Benchmark Implementation**:
|
||||
```csharp
|
||||
[MemoryDiagnoser]
|
||||
[MinColumn, MaxColumn, MeanColumn, MedianColumn]
|
||||
public class McpSdkBenchmarks
|
||||
{
|
||||
private PingTool _tool = null!;
|
||||
private SystemInfoResource _resource = null!;
|
||||
|
||||
[GlobalSetup]
|
||||
public void Setup()
|
||||
{
|
||||
_tool = new PingTool();
|
||||
_resource = new SystemInfoResource(...);
|
||||
}
|
||||
|
||||
[Benchmark]
|
||||
public async Task<McpToolResult> ExecutePingTool()
|
||||
{
|
||||
return await _tool.ExecuteAsync(
|
||||
new McpContext { TenantId = Guid.NewGuid() },
|
||||
CancellationToken.None);
|
||||
}
|
||||
|
||||
[Benchmark]
|
||||
public async Task<McpResourceContent> QuerySystemInfo()
|
||||
{
|
||||
return await _resource.GetContentAsync(
|
||||
new McpContext { TenantId = Guid.NewGuid() },
|
||||
CancellationToken.None);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Baseline** (custom implementation):
|
||||
- Tool execution: 150-200ms (P95)
|
||||
- Resource query: 80-120ms (P95)
|
||||
- Throughput: 70 req/s
|
||||
- Memory: 150-200 MB baseline
|
||||
|
||||
---
|
||||
|
||||
### 6. Compatibility Verification
|
||||
|
||||
**Goal**: Ensure SDK doesn't break existing architecture
|
||||
|
||||
**Checks**:
|
||||
1. **DI Container**: SDK services register without conflicts
|
||||
2. **Clean Architecture**: SDK fits into Infrastructure layer
|
||||
3. **CQRS Pattern**: SDK doesn't interfere with MediatR
|
||||
4. **Multi-Tenant**: TenantContext injection works
|
||||
5. **Authentication**: API Key middleware compatible
|
||||
|
||||
**Compatibility Matrix**:
|
||||
|
||||
| Component | SDK Compatible? | Notes |
|
||||
|-----------|----------------|-------|
|
||||
| ASP.NET Core DI | ✅ Yes | SDK uses standard DI |
|
||||
| MediatR CQRS | ✅ Yes | No conflicts |
|
||||
| EF Core | ✅ Yes | No database layer changes |
|
||||
| SignalR | ✅ Yes | Independent layers |
|
||||
| TenantContext | ⚠️ Verify | Need custom integration |
|
||||
| API Key Auth | ⚠️ Verify | Need custom middleware |
|
||||
| Redis Cache | ✅ Yes | No conflicts |
|
||||
|
||||
---
|
||||
|
||||
### 7. Team Training
|
||||
|
||||
**Goal**: Educate team on SDK usage
|
||||
|
||||
**Training Workshop** (2 hours):
|
||||
1. **SDK Overview** (30 min)
|
||||
- Architecture
|
||||
- Attribute system
|
||||
- Tool/Resource lifecycle
|
||||
|
||||
2. **Hands-On Coding** (60 min)
|
||||
- Create a simple Tool
|
||||
- Create a simple Resource
|
||||
- Test with Claude Desktop
|
||||
|
||||
3. **Q&A and Discussion** (30 min)
|
||||
- Migration concerns
|
||||
- Hybrid architecture strategy
|
||||
- Timeline and responsibilities
|
||||
|
||||
**Training Materials**:
|
||||
- Slide deck (20 slides)
|
||||
- Code examples repository
|
||||
- Migration guide document
|
||||
- FAQ document
|
||||
|
||||
---
|
||||
|
||||
## Tasks Breakdown
|
||||
|
||||
- [ ] [Task 1](sprint_5_story_13_task_1.md) - Install SDK and configure infrastructure - 1 day
|
||||
- [ ] [Task 2](sprint_5_story_13_task_2.md) - Implement PoC Tool (ping) - 1 day
|
||||
- [ ] [Task 3](sprint_5_story_13_task_3.md) - Implement PoC Resource (system.info) - 1 day
|
||||
- [ ] [Task 4](sprint_5_story_13_task_4.md) - Claude Desktop integration testing - 2 days
|
||||
- [ ] [Task 5](sprint_5_story_13_task_5.md) - Performance baseline benchmarking - 2 days
|
||||
- [ ] [Task 6](sprint_5_story_13_task_6.md) - Compatibility verification testing - 1 day
|
||||
- [ ] [Task 7](sprint_5_story_13_task_7.md) - Team training and documentation - 2 days
|
||||
|
||||
**Progress**: 0/7 tasks completed (0%)
|
||||
|
||||
## Deliverables
|
||||
|
||||
1. **Code**:
|
||||
- SDK NuGet packages installed
|
||||
- `PingTool.cs` (PoC Tool)
|
||||
- `SystemInfoResource.cs` (PoC Resource)
|
||||
- Benchmark suite
|
||||
|
||||
2. **Documentation**:
|
||||
- SDK Integration Guide (10 pages)
|
||||
- Performance Baseline Report (5 pages)
|
||||
- Compatibility Matrix (1 page)
|
||||
- Training slide deck (20 slides)
|
||||
|
||||
3. **Test Results**:
|
||||
- Claude Desktop integration test report
|
||||
- Benchmark results (charts and tables)
|
||||
- Compatibility verification report
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- PoC Tool parameter validation
|
||||
- PoC Resource JSON serialization
|
||||
- Error handling edge cases
|
||||
|
||||
### Integration Tests
|
||||
- Claude Desktop Tool call (stdio transport)
|
||||
- Claude Desktop Resource query
|
||||
- Error response handling
|
||||
|
||||
### Performance Tests
|
||||
- BenchmarkDotNet suite
|
||||
- Memory profiling
|
||||
- Throughput testing (100 concurrent requests)
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
| Risk ID | Description | Mitigation |
|
||||
|---------|-------------|------------|
|
||||
| RISK-013-1 | SDK incompatible with Clean Architecture | Early PoC will reveal issues, can adjust approach |
|
||||
| RISK-013-2 | Performance worse than custom implementation | Benchmark early, can optimize or abort migration |
|
||||
| RISK-013-3 | TenantContext integration doesn't work | Custom middleware can bridge the gap |
|
||||
| RISK-013-4 | Claude Desktop connection fails | Test with multiple clients (Continue, Cline) |
|
||||
| RISK-013-5 | Team learning curve too steep | Provide comprehensive training and pair programming |
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Technical Success
|
||||
- [ ] PoC Tool and Resource work end-to-end
|
||||
- [ ] Performance baseline recorded
|
||||
- [ ] Zero compatibility conflicts found
|
||||
- [ ] Claude Desktop integration successful
|
||||
|
||||
### Team Success
|
||||
- [ ] All team members complete training
|
||||
- [ ] Team confident in SDK approach (survey: >80% confidence)
|
||||
- [ ] Migration guide reviewed and approved
|
||||
|
||||
### Decision Gate
|
||||
**GO/NO-GO Decision**: After this story completes, team decides:
|
||||
- ✅ **GO**: Proceed with full migration (Stories 14-17)
|
||||
- ❌ **NO-GO**: Abort migration, keep custom implementation
|
||||
|
||||
**Decision Criteria**:
|
||||
- Performance acceptable (>=baseline or <10% regression)
|
||||
- Compatibility verified (zero blocking issues)
|
||||
- Team confident (>80% in survey)
|
||||
- No CRITICAL risks identified
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] SDK installed and configured
|
||||
- [ ] PoC Tool works (tested with Claude Desktop)
|
||||
- [ ] PoC Resource works (tested with Claude Desktop)
|
||||
- [ ] Performance baseline documented
|
||||
- [ ] Compatibility matrix complete (all green or yellow)
|
||||
- [ ] Team training conducted (100% attendance)
|
||||
- [ ] Migration guide reviewed and approved
|
||||
- [ ] Code reviewed by architect
|
||||
- [ ] GO/NO-GO decision made and documented
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Epic Story 0](sprint_5_story_0.md) - MCP SDK Migration Epic
|
||||
- [Research Report](../research/mcp-sdk-integration-research.md)
|
||||
- [Sprint 5 Plan](sprint_5.md)
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-11-09 by Product Manager Agent
|
||||
**Owner**: Backend Team Lead
|
||||
**Start Date**: 2025-11-27 (Week 1 of Sprint 5 Extension)
|
||||
**Target Date**: 2025-12-06 (End of Week 2)
|
||||
**Status**: Not Started
|
||||
Reference in New Issue
Block a user