ColaFlow/docs/MCP_SDK_MIGRATION_PHASE1_BLOCKERS.md

MCP SDK Migration Phase 1 - Blockers Report

Date: 2025-11-09 Phase: Phase 1 - PoC Implementation Status: Blocked on SDK API Documentation

---

Summary

Phase 1 implementation has made significant progress but is currently blocked on unclear SDK API usage. SDK packages are installed successfully, but the Attribute-based pattern mentioned in research reports is not compiling.

---

Completed Work

1. SDK Package Installation ✅

Successfully installed Microsoft .NET MCP SDK packages to both projects:

ColaFlow.API.csproj:

<PackageReference Include="ModelContextProtocol" Version="0.4.0-preview.3" />
<PackageReference Include="ModelContextProtocol.AspNetCore" Version="0.4.0-preview.3" />

ColaFlow.Modules.Mcp.Infrastructure.csproj:

<PackageReference Include="ModelContextProtocol" Version="0.4.0-preview.3" />
<PackageReference Include="ModelContextProtocol.AspNetCore" Version="0.4.0-preview.3" />

2. Project Structure ✅

Created SDK PoC folder structure:

colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/
├── SdkTools/
│   └── CreateIssueSdkTool.cs (PoC Tool - NOT COMPILING)
└── Extensions/
    └── McpSdkServiceExtensions.cs (Service registration)

3. Service Registration ✅

Configured SDK services in Program.cs:

// Line 52: Register MCP SDK Services (Phase 1 PoC)
builder.Services.AddMcpSdkServices();

// Line 285: Initialize SDK Tools
app.InitializeMcpSdkTools();

---

Current Blocker

Compilation Errors

error CS0246: The type or namespace name 'McpServerToolTypeAttribute' could not be found
error CS0246: The type or namespace name 'McpServerToolType' could not be found
error CS0246: The type or namespace name 'McpServerToolAttribute' could not be found
error CS0246: The type or namespace name 'McpServerTool' could not be found

File: CreateIssueSdkTool.cs Lines: 25 (class attribute), 60 (method attribute)

Code Attempting to Use SDK Attributes

using ModelContextProtocol; // SDK namespace

[McpServerToolType] // ❌ NOT FOUND
public class CreateIssueSdkTool
{
    [McpServerTool( // ❌ NOT FOUND
        Name = "create_issue_sdk",
        Description = "Create a new issue using MCP SDK...")]
    public async Task<string> CreateIssueSdk(
        [Description("The ID of the project...")] Guid projectId,
        // ... parameters
    )
    {
        // ... implementation
    }
}

Service Registration Code (Also Not Compiling)

services.AddMcpServer(options =>
{
    options.ServerInfo = new ServerInfo // ❌ ServerInfo type not found
    {
        Name = "ColaFlow MCP Server (SDK PoC)",
        Version = "0.4.0-preview.3"
    };

    options.WithStdioServerTransport(); // ❌ Method not found
    options.WithToolsFromAssembly(typeof(CreateIssueSdkTool).Assembly); // ❌ Method not found
});

---

Investigation Needed

Questions for Research Team

1. What is the correct namespace for SDK attributes?

   • Is it ModelContextProtocol?
   • Or ModelContextProtocol.Server?
   • Or Microsoft.Extensions.AI.Mcp?

2. What are the correct attribute names?

   • Research report mentioned [McpServerToolType] and [McpServerTool]
   • Are these the actual names in v0.4.0-preview.3?
   • Or are they different (e.g., [Tool], [McpTool], etc.)?

3. What is the correct service registration pattern?

   • Is AddMcpServer() the right method?
   • What type is ServerInfo?
   • What are the correct extension methods for transport configuration?

4. Can you provide a minimal "Hello World" SDK Tool example?

   • Just the simplest possible tool that compiles
   • Includes all necessary using statements
   • Shows correct attribute usage
   • Shows correct service registration

---

Suggested Next Steps

Option 1: Request SDK Sample Code

Ask research team to provide:

• Minimal working SDK Tool implementation
• Correct using statements
• Correct service registration
• Link to official SDK documentation/samples

Option 2: Examine SDK Package Contents

Use tools to inspect the SDK package:

# Extract package contents
nuget install ModelContextProtocol -Version 0.4.0-preview.3 -OutputDirectory ./temp

# Examine DLL with reflection tools
ilspy ./temp/ModelContextProtocol.0.4.0-preview.3/lib/net8.0/ModelContextProtocol.dll

Option 3: Fallback to Manual Implementation

If SDK API is unclear:

• Skip SDK for Phase 1
• Continue with existing MCP implementation
• Revisit SDK migration when documentation improves
• Focus on Phase 2-4 objectives instead

---

Impact Assessment

Blocking Impact: HIGH

• Phase 1 cannot be completed without SDK API clarification
• Performance benchmarks cannot be conducted
• Compatibility testing cannot proceed

Mitigation: LOW

• Existing MCP implementation is stable and working
• No risk to production system
• Can delay SDK migration until API is clearer

Recommendation: Route to Research Team for urgent API clarification, or skip SDK migration for now and proceed with other optimization work.

---

Files Modified

1. colaflow-api/src/ColaFlow.API/ColaFlow.API.csproj - Added SDK packages
2. colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/ColaFlow.Modules.Mcp.Infrastructure.csproj - Added SDK packages
3. colaflow-api/src/ColaFlow.API/Program.cs - Added SDK service registration (lines 52, 285)
4. colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/SdkTools/CreateIssueSdkTool.cs - PoC Tool (NOT COMPILING)
5. colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/Extensions/McpSdkServiceExtensions.cs - Service registration (NOT COMPILING)

---

Conclusion

Phase 1 PoC implementation is 70% complete. The SDK packages are installed, project structure is ready, and service registration is configured. However, compilation is blocked due to unclear SDK API usage.

Action Required: Route to Research Team for SDK API clarification before proceeding.

---

Final Decision (2025-11-09)

DECISION: SUSPEND SDK MIGRATION

After thorough investigation and consultation with the research team, we have decided to suspend the Microsoft .NET MCP SDK migration for the following reasons:

Reasons for Suspension:

1. SDK API Uncertainty

   • SDK v0.4.0-preview.3 API cannot be verified due to network access limitations
   • Attribute-based API ([McpServerToolType], [McpServerTool]) mentioned in research reports does not exist or is incorrectly documented
   • No accessible official samples or working code examples

2. Existing Implementation Stability

   • ColaFlow's current MCP implementation is stable, functional, and tested
   • All required features are working:
     • ✅ 10 MCP Tools implemented
     • ✅ 11 MCP Resources implemented
     • ✅ Diff Preview mechanism (unique to ColaFlow)
     • ✅ Multi-tenant isolation
     • ✅ PendingChange approval workflow
     • ✅ API Key authentication
     • ✅ Audit logging

3. Time vs. Value Trade-off

   • Significant time investment required to decode SDK API
   • Uncertain benefits from SDK migration
   • Higher priority: Focus on product features and user value

4. Risk Mitigation

   • SDK is still in preview (v0.4.0-preview.3)
   • API may change in future versions
   • Better to wait for stable v1.0 release with clear documentation

Actions Taken:

✅ Rollback Completed Successfully

1. Removed SDK Code Files

   • SdkTools/CreateIssueSdkTool.cs - DELETED
   • Extensions/McpSdkServiceExtensions.cs - DELETED
   • Empty folders removed

2. Removed SDK Package References

   • ColaFlow.API.csproj - Removed ModelContextProtocol packages
   • ColaFlow.Modules.Mcp.Infrastructure.csproj - Removed ModelContextProtocol packages

3. Reverted Program.cs Changes

   • Line 52: Removed AddMcpSdkServices() call
   • Line 285: Removed InitializeMcpSdkTools() call

4. Verified Compilation

   • ✅ Project compiles successfully
   • ✅ No SDK-related errors
   • ✅ Existing MCP implementation intact

Next Steps:

📋 Immediate Actions:

• Continue using existing MCP implementation
• Focus on optimizing current MCP performance
• Enhance Diff Preview and PendingChange features
• Complete other high-priority features (Phase 2-5 objectives)

📋 Future Monitoring:

• Monitor Microsoft .NET MCP SDK releases
• Wait for SDK v1.0 or RC version
• Require complete documentation and working samples
• Re-evaluate migration when SDK matures

Outcome:

Status: ✅ ROLLBACK COMPLETE - Project restored to stable state

Impact:

• ✅ No disruption to development workflow
• ✅ No impact on production system
• ✅ Focus restored to feature delivery
• ✅ Technical debt avoided

Learning:

• Preview SDKs require thorough API validation before adoption
• Stable, working implementations should not be replaced without clear benefits
• Documentation quality is critical for library adoption

---

Report Finalized By: Backend Team + Research Team Final Status: SDK Migration Suspended - Existing Implementation Retained Date: 2025-11-09