---
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