---
story_id: story_14
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: 2
---

# Story 14: Tool Migration to SDK Attributes

**Parent Epic**: [Story 0](sprint_5_story_0.md) - 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)
```csharp
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)
```csharp
[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](sprint_5_story_14_task_1.md) - Migrate P0 Tools (create_issue, update_status, add_comment, assign_issue) - 3 days
- [ ] [Task 2](sprint_5_story_14_task_2.md) - Migrate P1 Tools (create_sprint, update_sprint, log_decision) - 2 days
- [ ] [Task 3](sprint_5_story_14_task_3.md) - Migrate P2 Tools (generate_prd, split_epic, detect_risks) - 2 days
- [ ] [Task 4](sprint_5_story_14_task_4.md) - Update integration tests for all Tools - 2 days
- [ ] [Task 5](sprint_5_story_14_task_5.md) - 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