ColaFlow/docs/MCP_SDK_MIGRATION_PLAN.md

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:

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

[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

• SDK packages installed successfully
• At least 1 Tool migrated with Diff Preview preserved
• At least 1 Resource migrated
• 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)