442 lines
12 KiB
Markdown
442 lines
12 KiB
Markdown
---
|
|
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
|