ColaFlow/docs/plans/sprint_5_story_13.md

story_id, sprint_id, parent_story_id, status, priority, assignee, created_date, estimated_days, phase

story_id	sprint_id	parent_story_id	status	priority	assignee	created_date	estimated_days	phase
story_13	sprint_5	story_0	not_started	P0	backend	2025-11-09	10	1

Story 13: MCP SDK Foundation & Proof of Concept

Parent Epic: Story 0 - 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:

// ColaFlow.Modules.Mcp.csproj
<PackageReference Include="Microsoft.MCP" Version="1.0.0" />
<PackageReference Include="Microsoft.MCP.Server" Version="1.0.0" />

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

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

// 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):

{
  "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:

[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 - Install SDK and configure infrastructure - 1 day
• Task 2 - Implement PoC Tool (ping) - 1 day
• Task 3 - Implement PoC Resource (system.info) - 1 day
• Task 4 - Claude Desktop integration testing - 2 days
• Task 5 - Performance baseline benchmarking - 2 days
• Task 6 - Compatibility verification testing - 1 day
• Task 7 - 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 - MCP SDK Migration Epic
• Research Report
• Sprint 5 Plan

---

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