# MCP SDK Migration Plan

**Date**: 2025-11-12
**Status**: In Progress
**SDK Version**: ModelContextProtocol v0.4.0-preview.3

---

## Migration Strategy

We are migrating to the official Microsoft Model Context Protocol C# SDK while **preserving ColaFlow's unique Diff Preview and PendingChange approval mechanism**.

### Hybrid Approach

- **Use SDK for**: Protocol handling, transport layer, auto-discovery
- **Keep Custom**: Diff Preview, PendingChange workflow, multi-tenant isolation, authentication

---

## Completed Steps

### ✅ Step 1: Install SDK Packages (Completed)

**Packages Installed**:
- `ModelContextProtocol` v0.4.0-preview.3 → Infrastructure project
- `ModelContextProtocol.AspNetCore` v0.4.0-preview.3 → Infrastructure + API projects

**Files Modified**:
- `ColaFlow.Modules.Mcp.Infrastructure.csproj`
- `ColaFlow.API.csproj`

### ✅ Step 2: Create SDK-based Components (Completed)

**New Files Created**:

1. **SdkTools/CreateIssueSdkTool.cs** ✅
   - Attribute-based Tool definition using `[McpServerToolType]` and `[McpServerTool]`
   - Preserves Diff Preview mechanism
   - Returns PendingChange ID instead of direct execution

2. **SdkResources/ProjectsSdkResource.cs** ✅
   - Attribute-based Resource definition using `[McpServerResourceType]` and `[McpServerResource]`
   - Implements `ListProjectsAsync()` and `GetProjectAsync()`

3. **SdkPrompts/ProjectManagementPrompts.cs** ✅ (NEW FEATURE)
   - Implements Prompts功能 (previously missing in ColaFlow)
   - Provides 5 prompt templates:
     - `GeneratePrdPrompt` - Generate PRD for Epic
     - `SplitEpicToStoriesPrompt` - Break down Epic into Stories
     - `GenerateAcceptanceCriteriaPrompt` - Create acceptance criteria
     - `AnalyzeSprintProgressPrompt` - Analyze Sprint progress
     - `GenerateRetrospectivePrompt` - Sprint retrospective

### ✅ Step 3: Update Program.cs (Completed)

**Changes Made**:
- Kept `AddMcpModule()` for custom services (Diff Preview, PendingChange, etc.)
- Added SDK server registration with auto-discovery:
  ```csharp
  builder.Services.AddMcpServer(options =>
  {
      options.ServerInfo = new Microsoft.Extensions.AI.ServerInfo
      {
          Name = "ColaFlow MCP Server",
          Version = "1.0.0"
      };
  })
  .WithToolsFromAssembly(typeof(CreateIssueSdkTool).Assembly)
  .WithResourcesFromAssembly(typeof(ProjectsSdkResource).Assembly)
  .WithPromptsFromAssembly(typeof(ProjectManagementPrompts).Assembly);
  ```
- Added SDK endpoint mapping: `app.MapMcp("/mcp-sdk");`
- Legacy `/mcp` endpoint still handled by custom middleware

---

## Next Steps

### 🔄 Step 4: Migrate Remaining Tools (10 tools to migrate)

**Current Tools to Migrate**:
1. ✅ `CreateIssueTool` → `CreateIssueSdkTool` (Done)
2. ⏳ `UpdateIssueTool` → `UpdateIssueSdkTool`
3. ⏳ `UpdateIssueStatusTool` → `UpdateIssueStatusSdkTool`
4. ⏳ `AssignIssueTool` → `AssignIssueSdkTool`
5. ⏳ `CreateSprintTool` → `CreateSprintSdkTool`
6. ⏳ `StartSprintTool` → `StartSprintSdkTool`
7. ⏳ `AddCommentTool` → `AddCommentSdkTool`
8. ⏳ `CreateEpicTool` → `CreateEpicSdkTool`
9. ⏳ `LinkIssuesTool` → `LinkIssuesSdkTool`
10. ⏳ `CreateProjectTool` → `CreateProjectSdkTool`

**Pattern to Follow** (from CreateIssueSdkTool):
```csharp
[McpServerToolType]
public class XxxSdkTool
{
    // Constructor injection
    public XxxSdkTool(IDependencies...) { }

    [McpServerTool]
    [Description("Tool description")]
    public async Task<string> MethodNameAsync(
        [Description("param desc")] ParamType param,
        CancellationToken cancellationToken = default)
    {
        // 1. Validate input
        // 2. Generate Diff Preview
        // 3. Create PendingChange
        // 4. Return PendingChange info (NOT direct result)
    }
}
```

### 🔄 Step 5: Migrate Remaining Resources (10 resources to migrate)

**Current Resources to Migrate**:
1. ✅ `ProjectsListResource` → `ProjectsSdkResource.ListProjectsAsync()` (Done)
2. ✅ `ProjectsGetResource` → `ProjectsSdkResource.GetProjectAsync()` (Done)
3. ⏳ `IssuesSearchResource` → `IssuesSdkResource.SearchIssuesAsync()`
4. ⏳ `IssuesGetResource` → `IssuesSdkResource.GetIssueAsync()`
5. ⏳ `SprintsCurrentResource` → `SprintsSdkResource.GetCurrentSprintAsync()`
6. ⏳ `UsersListResource` → `UsersSdkResource.ListUsersAsync()`
7. ⏳ `EpicsListResource` → (Can be part of IssuesResource with type filter)
8. ⏳ `StoriesListResource` → (Can be part of IssuesResource with type filter)
9. ⏳ `TasksListResource` → (Can be part of IssuesResource with type filter)
10. ⏳ `SprintsBacklogResource` → `SprintsSdkResource.GetBacklogAsync()`
11. ⏳ `ReportsBurndownResource` → `ReportsSdkResource.GetBurndownAsync()`

### 🔄 Step 6: Test SDK Integration

**Testing Checklist**:
- [ ] Test SDK endpoint `/mcp-sdk` responds to `initialize`
- [ ] Test Tools discovery via `tools/list`
- [ ] Test Resources discovery via `resources/list`
- [ ] Test Prompts discovery via `prompts/list` (new feature!)
- [ ] Test Tool execution with Diff Preview mechanism
- [ ] Test Resource reading with tenant isolation
- [ ] Test Prompt retrieval
- [ ] Verify legacy `/mcp` endpoint still works

### 🔄 Step 7: Update Documentation

**Documents to Update**:
- [ ] `docs/architecture/mcp-server-architecture.md` - Add SDK section
- [ ] `README.md` - Update MCP integration instructions
- [ ] API documentation - Document new `/mcp-sdk` endpoint
- [ ] Create migration guide for future SDK updates

### 🔄 Step 8: Deprecate Legacy Implementation (Optional)

**Decision Point**: Should we keep both implementations?

**Option A: Keep Both** (Recommended for now)
- `/mcp` - Legacy custom implementation
- `/mcp-sdk` - New SDK-based implementation
- Allows gradual migration and A/B testing

**Option B: Full Migration**
- Remove custom middleware
- Only use `/mcp-sdk`
- Requires thorough testing

---

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                     ColaFlow MCP Server                      │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌────────────────────┐      ┌────────────────────────┐    │
│  │ Legacy Endpoint    │      │ SDK Endpoint           │    │
│  │ POST /mcp          │      │ POST /mcp-sdk          │    │
│  │ (Custom Middleware)│      │ (Official SDK)         │    │
│  └────────────────────┘      └────────────────────────┘    │
│           │                            │                     │
│           ├──────────┬─────────────────┤                    │
│           │          │                 │                     │
│  ┌────────▼────┐  ┌──▼──────────┐  ┌──▼──────────────┐    │
│  │ IMcpTool    │  │ [McpTool]   │  │ [McpResource]   │    │
│  │ (Legacy)    │  │ (SDK-based) │  │ (SDK-based)     │    │
│  └────────┬────┘  └──┬──────────┘  └──┬──────────────┘    │
│           │          │                 │                     │
│           └──────────┼─────────────────┘                    │
│                      │                                       │
│           ┌──────────▼──────────┐                           │
│           │ Diff Preview Service │ (Preserved)              │
│           │ PendingChange Service│ (Preserved)              │
│           │ Multi-tenant Context │ (Preserved)              │
│           └─────────────────────┘                           │
│                                                               │
└─────────────────────────────────────────────────────────────┘
```

---

## Key Design Decisions

### ✅ Preserve Diff Preview Mechanism

**Why**: This is ColaFlow's core competitive advantage for safe AI collaboration.

**How**: SDK Tools return PendingChange ID instead of direct execution results.

### ✅ Keep Custom Services

**Services Preserved**:
- `IPendingChangeService` - Manages approval workflow
- `DiffPreviewService` - Generates change previews
- `IMcpApiKeyService` - API key authentication
- `ITenantContext` - Multi-tenant isolation
- `IMcpNotificationService` - SignalR real-time notifications

### ✅ Add Prompts Feature

**New Capability**: Prompts were missing in ColaFlow but supported by SDK.

**Value**: Provides AI with pre-defined templates for common project management tasks.

---

## Risks and Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| SDK API Changes | High | SDK is preview version, lock to v0.4.0-preview.3 |
| Dual Endpoints Confusion | Medium | Clear documentation, deprecation plan |
| Performance Regression | Medium | Load testing before production |
| Breaking Changes | High | Keep legacy endpoint as fallback |

---

## Success Criteria

- [x] SDK packages installed successfully
- [x] At least 1 Tool migrated with Diff Preview preserved
- [x] At least 1 Resource migrated
- [x] Prompts feature implemented
- [ ] All 10 Tools migrated
- [ ] All 11 Resources migrated
- [ ] SDK endpoint passes all integration tests
- [ ] Documentation updated
- [ ] No performance degradation

---

## Timeline

**Estimated Time**: 5-7 days

- **Day 1**: ✅ Setup and initial migration (Completed)
- **Day 2-3**: Migrate remaining Tools
- **Day 4**: Migrate remaining Resources
- **Day 5**: Testing and bug fixes
- **Day 6**: Documentation
- **Day 7**: Review and production readiness

---

## Notes

- SDK version `0.4.0-preview.3` is a preview release - expect potential breaking changes
- Official SDK does NOT support Diff Preview natively - we've adapted it
- Legacy implementation will remain as fallback during transition
- This migration brings us into compliance with MCP specification while maintaining unique features

---

**Last Updated**: 2025-11-12
**Migration Lead**: Claude (ColaFlow Coordinator)
**Status**: 40% Complete (3/8 major steps done)