ColaFlow/docs/plans/sprint_5_story_14.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_14	sprint_5	story_0	not_started	P0	backend	2025-11-09	10	2

Story 14: Tool Migration to SDK Attributes

Parent Epic: Story 0 - Integrate Microsoft .NET MCP SDK Phase: 2 - Tool Migration (Week 3-4) Priority: P0 - Critical Estimated Effort: 10 days (2 weeks) Dependencies: Story 13 (Foundation must be complete)

User Story

As a backend developer, I want to migrate all 10 MCP Tools from custom implementation to SDK attribute-based registration, So that we reduce boilerplate code and improve maintainability while preserving DiffPreview integration.

Business Value

• Code Reduction: Remove 300-400 lines of custom Tool infrastructure
• Developer Experience: Attribute-based registration is cleaner and more intuitive
• Performance: SDK optimizations improve Tool execution by 20-30%
• Maintainability: Microsoft maintains protocol layer, we focus on business logic

Tools to Migrate (10 Total)

High Priority Tools (P0)

1. create_issue - Create Epic/Story/Task
2. update_status - Change issue status
3. add_comment - Add comment to issue
4. assign_issue - Assign issue to user

Medium Priority Tools (P1)

5. create_sprint - Create new Sprint
6. update_sprint - Update Sprint details
7. log_decision - Log architecture decision

Low Priority Tools (P2)

8. generate_prd - AI-generate PRD from description
9. split_epic - Split Epic into Stories
10. detect_risks - Detect project risks

Migration Pattern

Before (Custom Implementation)

public class CreateIssueTool : IMcpTool
{
    public string Name => "create_issue";
    public string Description => "Create a new issue";
    public McpToolInputSchema InputSchema => new()
    {
        Type = "object",
        Properties = new Dictionary<string, object>
        {
            ["projectId"] = new { type = "string", format = "uuid" },
            ["title"] = new { type = "string", minLength = 1 }
        },
        Required = new[] { "projectId", "title" }
    };

    public async Task<McpToolResult> ExecuteAsync(
        McpToolCall toolCall,
        CancellationToken ct)
    {
        // Manual parameter extraction
        var projectId = GetParam<Guid>(toolCall.Arguments, "projectId");
        var title = GetParam<string>(toolCall.Arguments, "title");

        // Business logic...
    }
}

After (SDK Attributes)

[McpTool(
    Name = "create_issue",
    Description = "Create a new issue (Epic/Story/Task) with Diff Preview"
)]
public class CreateIssueTool
{
    private readonly IDiffPreviewService _diffPreview;
    private readonly IPendingChangeService _pendingChange;

    public CreateIssueTool(
        IDiffPreviewService diffPreview,
        IPendingChangeService pendingChange)
    {
        _diffPreview = diffPreview;
        _pendingChange = pendingChange;
    }

    [McpToolParameter(Required = true)]
    public Guid ProjectId { get; set; }

    [McpToolParameter(Required = true, MinLength = 1, MaxLength = 200)]
    public string Title { get; set; } = string.Empty;

    [McpToolParameter]
    public string? Description { get; set; }

    [McpToolParameter]
    public string Priority { get; set; } = "Medium";

    public async Task<McpToolResult> ExecuteAsync(
        McpContext context,
        CancellationToken cancellationToken)
    {
        // Parameters auto-bound by SDK

        // Generate Diff Preview (preserve existing logic)
        var diff = await _diffPreview.GeneratePreviewAsync(
            null, // CREATE operation
            new { ProjectId, Title, Description, Priority },
            "CREATE",
            cancellationToken);

        // Create PendingChange (preserve existing workflow)
        var pendingChange = await _pendingChange.CreateAsync(
            "create_issue",
            diff,
            cancellationToken);

        return McpToolResult.Success(new
        {
            PendingChangeId = pendingChange.Id,
            Message = "Issue creation pending approval",
            DiffPreview = diff
        });
    }
}

Key Changes

What Changes

• ✅ Tool registration (custom → SDK attributes)
• ✅ Parameter declaration (schema → properties)
• ✅ Parameter validation (manual → SDK automatic)
• ✅ Error handling (custom → SDK standard)

What Stays the Same

• ✅ DiffPreviewService integration (preserved)
• ✅ PendingChangeService workflow (preserved)
• ✅ TenantContext access (preserved via McpContext)
• ✅ API Key authentication (preserved)
• ✅ Business logic (unchanged)

Acceptance Criteria

• All 10 Tools migrated to [McpTool] attributes
• DiffPreview workflow works for all write operations
• PendingChange creation works correctly
• Tool parameter validation automatic (SDK-based)
• Integration tests pass (>80% coverage)
• Performance improved by ≥20% (measured)
• Claude Desktop can call all migrated Tools
• Zero breaking changes for MCP clients

Tasks Breakdown

• Task 1 - Migrate P0 Tools (create_issue, update_status, add_comment, assign_issue) - 3 days
• Task 2 - Migrate P1 Tools (create_sprint, update_sprint, log_decision) - 2 days
• Task 3 - Migrate P2 Tools (generate_prd, split_epic, detect_risks) - 2 days
• Task 4 - Update integration tests for all Tools - 2 days
• Task 5 - Performance testing and optimization - 1 day

Progress: 0/5 tasks completed (0%)

Testing Strategy

Unit Tests (Per Tool)

• Parameter validation (required, types, ranges)
• DiffPreview generation correctness
• PendingChange creation
• Error handling (invalid params, missing tenant)

Integration Tests (End-to-End)

• Claude Desktop Tool calls
• Diff Preview workflow
• Approval/rejection flow
• Multi-tenant isolation

Performance Tests

• Benchmark each Tool (before/after)
• Target: 20-30% improvement
• Memory profiling

Success Metrics

• Code Reduction: -300 lines (Tool infrastructure)
• Performance: +20-30% faster Tool execution
• Test Coverage: Maintain 80%+
• Developer Time: 50% faster to add new Tools

Definition of Done

• All 10 Tools migrated to SDK attributes
• DiffPreview integration verified (all Tools)
• Integration tests pass (>80% coverage)
• Performance benchmarks show ≥20% improvement
• Code reviewed and approved
• Documentation updated

---

Created: 2025-11-09 by Product Manager Agent Owner: Backend Team Start Date: 2025-12-09 (Week 3) Target Date: 2025-12-20 (End of Week 4) Status: Not Started