ColaFlow/docs/plans/sprint_5.md

sprint_id, milestone, status, created_date, start_date, target_end_date, duration_weeks

sprint_id	milestone	status	created_date	start_date	target_end_date	duration_weeks
sprint_5	M2	not_started	2025-11-06	2025-11-27	2026-01-22	8

Sprint 5: MCP Server Foundation - Phase 1-3

Milestone: M2 - MCP Server Implementation Goal: Build the foundational MCP Server infrastructure to enable AI agents (Claude, ChatGPT) to safely read and modify ColaFlow project data through the MCP protocol.

Sprint Scope: Phase 1-3 of MCP Server implementation (Weeks 1-6 from architecture roadmap)

Sprint Context

Background

ColaFlow M1 core features are 82% complete (Day 17). M2 phase focuses on implementing the MCP (Model Context Protocol) Server to enable AI integration. The architecture design document provides a comprehensive 16-week implementation plan. This Sprint covers the first 6 weeks (Phase 1-3), establishing the foundation for AI-powered project management.

Reference Documents

• Architecture Design: docs/architecture/mcp-server-architecture.md (1,867 lines, 73KB)
• MCP Suggestions: docs/mcp-suggestion.md
• Product Roadmap: product.md - M2 section

M2 Key Objectives

1. Let AI become a true team member
2. AI can read project data (Projects, Epics, Stories, Tasks, Sprints)
3. AI can execute operations (create tasks, update status, assign users)
4. All AI write operations require human approval (Diff Preview mechanism)
5. Complete audit trail for all AI operations

Sprint Objectives (Phase 1-3)

Phase 1: Foundation (Week 1-2)

• Establish MCP protocol infrastructure
• Implement API Key authentication
• Basic error handling and logging

Phase 2: Resources (Week 3-4)

• Implement read-only data exposure (5 core Resources)
• Multi-tenant isolation verification
• Redis caching integration

Phase 3: Tools & Diff Preview (Week 5-6)

• Implement write operations (3 core Tools)
• Build Diff Preview mechanism
• SignalR real-time notifications

Stories

Phase 1 Stories (Week 1-2)

• story_1 - MCP Protocol Handler Implementation - not_started - P0 Critical - 3 days
• story_2 - API Key Management System - not_started - P0 Critical - 2 days
• story_3 - MCP Domain Layer Design - not_started - P0 Critical - 2 days
• story_4 - Error Handling & Logging - not_started - P0 Critical - 1 day

Phase 2 Stories (Week 3-4)

• story_5 - Core MCP Resources Implementation - not_started - P0 Critical - 3 days
• story_6 - Resource Registration & Discovery - not_started - P0 Critical - 1 day
• story_7 - Multi-Tenant Isolation Verification - not_started - P0 Critical - 2 days
• story_8 - Redis Caching Integration - not_started - P1 High - 2 days

Phase 3 Stories (Week 5-6)

• story_9 - Diff Preview Service Implementation - not_started - P0 Critical - 2 days
• story_10 - PendingChange Management - not_started - P0 Critical - 2 days
• story_11 - Core MCP Tools Implementation - not_started - P0 Critical - 3 days
• story_12 - SignalR Real-Time Notifications - not_started - P0 Critical - 1 day

Progress: 0/12 stories completed (0%)

---

🚀 NEW: Microsoft .NET MCP SDK Migration (Epic)

Background

After completing Phase 1-3 (Stories 1-12) using custom MCP implementation, the research team discovered Microsoft's official .NET MCP SDK. Research report shows:

• 60-70% code reduction (SDK handles protocol, registration, transport)
• 30-40% performance improvement (optimized JSON parsing, middleware)
• Future-proof: Microsoft maintains protocol updates
• Hybrid architecture: SDK handles boring stuff, ColaFlow keeps unique features (Diff Preview, multi-tenant)

Epic Story: SDK Migration

• story_0 - EPIC: Integrate Microsoft .NET MCP SDK - not_started - P0 Critical - 8 weeks

SDK Migration Stories (Phase 1-5 Extension)

Phase 1: Foundation & PoC (Week 1-2)

• story_13 - MCP SDK Foundation & Proof of Concept - not_started - P0 Critical - 10 days

Phase 2: Tool Migration (Week 3-4)

• story_14 - Tool Migration to SDK Attributes - not_started - P0 Critical - 10 days

Phase 3: Resource Migration (Week 5)

• story_15 - Resource Migration to SDK Attributes - not_started - P0 Critical - 5 days

Phase 4: Transport Layer (Week 6)

• story_16 - Transport Layer Migration to SDK - not_started - P0 Critical - 5 days

Phase 5: Testing & Optimization (Week 7-8)

• story_17 - Testing, Optimization & Documentation - not_started - P0 Critical - 10 days

SDK Migration Progress: 0/5 stories completed (0%)

SDK Migration Timeline

Prerequisite: Complete Stories 1-12 (custom implementation)

Week 1-2: Story 13 - SDK Foundation & PoC

• Install SDK, create PoC Tool/Resource
• Performance baseline benchmarking
• Compatibility verification
• Team training

Week 3-4: Story 14 - Tool Migration

• Migrate 10 Tools to [McpTool] attributes
• Preserve DiffPreview integration
• Integration testing

Week 5: Story 15 - Resource Migration

• Migrate 11 Resources to [McpResource] attributes
• Preserve multi-tenant isolation + Redis caching

Week 6: Story 16 - Transport Layer

• Replace custom middleware with SDK transports
• Configure stdio + HTTP/SSE
• Preserve API Key auth + field-level permissions

Week 7-8: Story 17 - Testing & Docs

• Comprehensive testing (integration, performance, security)
• Documentation update
• Production deployment

Total SDK Migration: 8 weeks (40 days) Expected Benefits: 60-70% code reduction, 20-40% performance gain

---

Sprint Total Progress

Phase 1-3 (Custom Implementation): 0/12 stories (0%) SDK Migration (Phase 1-5): 0/5 stories (0%) Overall Sprint: 0/17 stories (0%)

---

Architecture Overview

Clean Architecture + CQRS + DDD

┌─────────────────────────────────────┐
│     Presentation Layer              │
│  - MCP Protocol Handler (JSON-RPC)  │
│  - REST API for MCP Management      │
└─────────────────┬───────────────────┘
                  ↓
┌─────────────────────────────────────┐
│     Application Layer               │
│  - McpResourceService               │
│  - McpToolService                   │
│  - DiffPreviewService               │
│  - PendingChangeService             │
└─────────────────┬───────────────────┘
                  ↓
┌─────────────────────────────────────┐
│     Domain Layer                    │
│  - McpApiKey (Aggregate Root)       │
│  - PendingChange (Aggregate Root)   │
│  - DiffPreview (Value Object)       │
└─────────────────┬───────────────────┘
                  ↓
┌─────────────────────────────────────┐
│     Infrastructure Layer            │
│  - EF Core Repositories             │
│  - Redis Cache                      │
│  - SignalR Hub                      │
└─────────────────────────────────────┘

Core Components

1. MCP Protocol Handler: JSON-RPC 2.0 protocol parser and router
2. McpResourceService: Read-only data exposure (5 Resources)
3. McpToolService: Write operations with Diff Preview (3 Tools)
4. DiffPreviewService: Generate before/after data snapshots
5. PendingChangeService: Manage approval workflow
6. McpApiKeyService: API Key authentication and authorization

---

Phase 1: Foundation (Week 1-2)

Story 1: MCP Protocol Handler Implementation (3 days) - P0 CRITICAL

Goal: Implement JSON-RPC 2.0 protocol handler for MCP communication

Scope:

• Create MCP Protocol Handler interfaces and base classes
• Implement JSON-RPC 2.0 message parsing
• Build request/response routing mechanism
• Implement MCP initialize handshake
• Error handling and validation
• Unit tests for protocol parsing

Acceptance Criteria:

• MCP protocol initialize handshake succeeds
• JSON-RPC 2.0 messages correctly parsed
• Request routing to Resource/Tool/Prompt handlers works
• Error responses conform to MCP specification
• Unit test coverage > 80%

Deliverables:

• IMcpProtocolHandler interface
• McpProtocolHandler implementation
• McpRequest / McpResponse DTOs
• McpResourceController / McpToolController base classes
• Unit tests

Technical Details:

public interface IMcpProtocolHandler
{
    Task<McpResponse> HandleRequestAsync(
        McpRequest request,
        CancellationToken cancellationToken);
}

public class McpRequest
{
    public string JsonRpc { get; set; } = "2.0";
    public string Method { get; set; }
    public object? Params { get; set; }
    public string? Id { get; set; }
}

public class McpResponse
{
    public string JsonRpc { get; set; } = "2.0";
    public object? Result { get; set; }
    public McpError? Error { get; set; }
    public string? Id { get; set; }
}

---

Story 2: API Key Management System (2 days) - P0 CRITICAL

Goal: Implement secure API Key creation, validation, and management

Scope:

• Create McpApiKey aggregate root (Domain Layer)
• Implement API Key generation (40-char random string)
• BCrypt hashing for secure storage
• API Key validation middleware
• CRUD operations via REST API
• Database migration (mcp_api_keys table)
• Multi-tenant isolation

Acceptance Criteria:

• API Key creation generates unique 40-char key
• API Key hashed with BCrypt before storage
• Validation middleware authenticates requests
• Unauthorized requests return 401
• API Keys isolated per tenant
• CRUD endpoints work correctly

Database Schema:

CREATE TABLE mcp_api_keys (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    key_hash VARCHAR(64) NOT NULL UNIQUE,
    key_prefix VARCHAR(16) NOT NULL,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    permissions JSONB NOT NULL,
    ip_whitelist JSONB,
    status INT NOT NULL DEFAULT 1,
    last_used_at TIMESTAMP NULL,
    usage_count BIGINT NOT NULL DEFAULT 0,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    expires_at TIMESTAMP NOT NULL,
    revoked_at TIMESTAMP NULL,

    INDEX idx_key_prefix (key_prefix),
    INDEX idx_tenant_user (tenant_id, user_id),
    INDEX idx_expires_at (expires_at)
);

API Endpoints:

• POST /api/mcp/keys - Create API Key
• GET /api/mcp/keys - List API Keys
• DELETE /api/mcp/keys/{id} - Revoke API Key

---

Story 3: MCP Domain Layer Design (2 days) - P0 CRITICAL

Goal: Design and implement MCP domain entities, aggregates, and events

Scope:

• Create McpApiKey aggregate root
• Create PendingChange aggregate root
• Create DiffPreview value object
• Define domain events (ApiKeyCreated, PendingChangeCreated, etc.)
• Implement domain logic and validation
• Unit tests for domain entities

Acceptance Criteria:

• All aggregates correctly implement entity base classes
• Domain events fire at appropriate lifecycle points
• Business rules enforced in domain entities
• Aggregates are immutable where appropriate
• Unit test coverage > 90% for domain layer

Aggregates:

1. McpApiKey (Aggregate Root)

public class McpApiKey : AggregateRoot
{
    public Guid TenantId { get; private set; }
    public Guid UserId { get; private set; }
    public string KeyHash { get; private set; }
    public string KeyPrefix { get; private set; }
    public string Name { get; private set; }
    public ApiKeyPermissions Permissions { get; private set; }
    public ApiKeyStatus Status { get; private set; }
    public DateTime ExpiresAt { get; private set; }

    public static McpApiKey Create(string name, Guid tenantId, Guid userId);
    public void Revoke();
    public void UpdatePermissions(ApiKeyPermissions permissions);
}

2. PendingChange (Aggregate Root)

public class PendingChange : AggregateRoot
{
    public Guid TenantId { get; private set; }
    public Guid ApiKeyId { get; private set; }
    public string ToolName { get; private set; }
    public DiffPreview Diff { get; private set; }
    public PendingChangeStatus Status { get; private set; }
    public DateTime ExpiresAt { get; private set; }
    public Guid? ApprovedBy { get; private set; }

    public static PendingChange Create(string toolName, DiffPreview diff);
    public void Approve(Guid userId);
    public void Reject(Guid userId, string reason);
    public void Expire();
}

3. DiffPreview (Value Object)

public class DiffPreview : ValueObject
{
    public string Operation { get; private set; } // CREATE, UPDATE, DELETE
    public string EntityType { get; private set; }
    public Guid? EntityId { get; private set; }
    public object? BeforeData { get; private set; }
    public object? AfterData { get; private set; }
    public DiffField[] ChangedFields { get; private set; }
}

Domain Events:

• ApiKeyCreatedEvent
• ApiKeyRevokedEvent
• PendingChangeCreatedEvent
• PendingChangeApprovedEvent
• PendingChangeRejectedEvent
• PendingChangeExpiredEvent

---

Story 4: Error Handling & Logging (1 day) - P0 CRITICAL

Goal: Implement comprehensive error handling and structured logging for MCP operations

Scope:

• Create MCP-specific exception classes
• Implement exception-to-MCP-error mapping
• Structured logging with Serilog
• Request/response logging middleware
• Performance monitoring (timing)
• Error rate tracking

Acceptance Criteria:

• All exceptions mapped to MCP error responses
• Structured logs include correlation IDs
• Request/response logged at DEBUG level
• Errors logged at ERROR level with stack traces
• Performance metrics captured
• No sensitive data in logs

MCP Error Codes:

public enum McpErrorCode
{
    ParseError = -32700,
    InvalidRequest = -32600,
    MethodNotFound = -32601,
    InvalidParams = -32602,
    InternalError = -32603,
    Unauthorized = -32001,
    Forbidden = -32002,
    NotFound = -32003,
    ValidationFailed = -32004
}

---

Phase 2: Resources (Week 3-4)

Story 5: Core MCP Resources Implementation (3 days) - P0 CRITICAL

Goal: Implement 5 core read-only MCP Resources

Scope: Implement the following Resources:

1. colaflow://projects.list - List all projects
2. colaflow://projects.get/{id} - Get project details
3. colaflow://issues.search - Search issues (with filters)
4. colaflow://issues.get/{id} - Get issue details
5. colaflow://sprints.current - Get current active Sprint
6. colaflow://users.list - List team members

Acceptance Criteria:

• All 5 Resources return correct data
• Data respects multi-tenant isolation (TenantId filter)
• Query parameters work (status, priority, assignee, etc.)
• Pagination implemented (limit, offset)
• Response time < 200ms
• Unit and integration tests pass

Resource Interface:

public interface IMcpResource
{
    string Uri { get; }
    string Name { get; }
    string Description { get; }
    string MimeType { get; }

    Task<McpResourceContent> GetContentAsync(
        McpResourceRequest request,
        CancellationToken cancellationToken);
}

Example Implementation:

public class ProjectsListResource : IMcpResource
{
    public string Uri => "colaflow://projects.list";
    public string Name => "Projects List";
    public string Description => "List all projects in current tenant";
    public string MimeType => "application/json";

    private readonly IProjectRepository _projectRepo;
    private readonly ITenantContext _tenantContext;

    public async Task<McpResourceContent> GetContentAsync(...)
    {
        var projects = await _projectRepo.GetAllAsync(
            _tenantContext.CurrentTenantId);

        return new McpResourceContent
        {
            Uri = Uri,
            MimeType = MimeType,
            Text = JsonSerializer.Serialize(new { projects })
        };
    }
}

Response Format:

{
  "projects": [
    {
      "id": "uuid",
      "name": "ColaFlow Development",
      "key": "COLA",
      "status": "Active",
      "owner": { "id": "uuid", "name": "John Doe" },
      "issueCount": 145,
      "memberCount": 8,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

---

Story 6: Resource Registration & Discovery (1 day) - P0 CRITICAL

Goal: Implement plugin-based Resource registration and discovery mechanism

Scope:

• Create IMcpRegistry interface
• Implement auto-discovery of Resources via Reflection
• Build Resource catalog (resources/list endpoint)
• Resource versioning support
• Configuration-based Resource enable/disable

Acceptance Criteria:

• All Resources auto-registered at startup
• resources/list returns complete catalog
• Resources can be disabled via config
• Resource metadata complete (URI, name, description, schema)

Registry Interface:

public interface IMcpRegistry
{
    void RegisterResource(IMcpResource resource);
    void RegisterTool(IMcpTool tool);
    void RegisterPrompt(IMcpPrompt prompt);

    IMcpResource? GetResource(string uri);
    IReadOnlyList<IMcpResource> GetAllResources();
}

---

Story 7: Multi-Tenant Isolation Verification (2 days) - P0 CRITICAL

Goal: Verify 100% multi-tenant data isolation for all MCP operations

Scope:

• Implement TenantContext service for MCP
• Apply EF Core Global Query Filters
• Create integration tests for cross-tenant access attempts
• Test all 5 Resources with multi-tenant scenarios
• Security audit for tenant leaks

Acceptance Criteria:

• TenantContext correctly extracts tenant from API Key
• Global Query Filters applied to all entities
• Cross-tenant access attempts return 404 (not 403)
• Integration tests verify 100% isolation
• No tenant leaks found in security audit

Test Scenarios:

• Tenant A cannot read Tenant B's projects
• API Key from Tenant A cannot access Tenant B's issues
• Search queries never return cross-tenant results
• Direct ID access fails for other tenant's data

---

Story 8: Redis Caching Integration (2 days) - P1 HIGH

Goal: Implement Redis caching for frequently accessed MCP Resources

Scope:

• Integrate Redis distributed cache
• Implement cache-aside pattern for Resources
• Configure TTL per Resource type (5 minutes default)
• Cache invalidation on data updates (domain events)
• Cache hit rate monitoring

Acceptance Criteria:

• Redis cache integrated into Resource queries
• Cache hit rate > 80% for hot Resources
• TTL correctly enforced (5 minutes)
• Cache invalidated on data changes
• Performance improvement measured (30-50% faster)

Cached Resources:

• projects.list (TTL: 5 min)
• users.list (TTL: 5 min)
• sprints.current (TTL: 2 min)
• issues.search (TTL: 2 min, cache by query params)

Cache Key Format: mcp:{tenantId}:{resourceUri}:{params_hash}

---

Phase 3: Tools & Diff Preview (Week 5-6)

Story 9: Diff Preview Service Implementation (2 days) - P0 CRITICAL

Goal: Implement service to generate before/after data previews for write operations

Scope:

• Create DiffPreviewService class
• Implement snapshot capture (before data)
• Simulate operation execution (after data)
• Calculate field-level differences
• Format diff as human-readable output
• Generate diff HTML for UI display

Acceptance Criteria:

• Diff Preview accurately shows changed fields
• Before/after snapshots captured correctly
• HTML diff output renders in UI
• Nested object changes handled
• Array/list changes detected

Service Interface:

public interface IDiffPreviewService
{
    Task<DiffPreview> GeneratePreviewAsync<TEntity>(
        Guid? entityId,
        TEntity afterData,
        string operation,
        CancellationToken cancellationToken);
}

Diff Output Example:

{
  "operation": "UPDATE",
  "entityType": "Issue",
  "entityId": "uuid",
  "entityKey": "COLA-146",
  "changedFields": [
    {
      "fieldName": "title",
      "displayName": "Title",
      "oldValue": "Implement MCP Server",
      "newValue": "Implement MCP Server (updated)",
      "diffHtml": "<del>Implement MCP Server</del> <ins>Implement MCP Server (updated)</ins>"
    },
    {
      "fieldName": "priority",
      "displayName": "Priority",
      "oldValue": "High",
      "newValue": "Critical"
    }
  ]
}

---

Story 10: PendingChange Management (2 days) - P0 CRITICAL

Goal: Implement approval workflow for AI write operations

Scope:

• Implement PendingChangeService
• CRUD operations for PendingChange entity
• Approval/rejection workflow
• 24-hour auto-expiration mechanism (background job)
• Query pending changes by tenant/user
• Persistence to PostgreSQL

Acceptance Criteria:

• PendingChange created correctly with Diff Preview
• Approve action executes actual operation
• Reject action logs reason and notifies AI
• 24-hour expiration works (background task)
• Query APIs return correct results

Database Schema:

CREATE TABLE mcp_pending_changes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    api_key_id UUID NOT NULL REFERENCES mcp_api_keys(id),
    tool_name VARCHAR(100) NOT NULL,
    operation VARCHAR(20) NOT NULL,
    entity_type VARCHAR(50) NOT NULL,
    entity_id UUID,
    diff_data JSONB NOT NULL,
    status INT NOT NULL DEFAULT 0, -- PendingApproval, Approved, Rejected, Expired
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    expires_at TIMESTAMP NOT NULL,
    approved_by UUID REFERENCES users(id),
    approved_at TIMESTAMP,
    rejection_reason TEXT,

    INDEX idx_tenant_status (tenant_id, status),
    INDEX idx_expires (expires_at) WHERE status = 0
);

API Endpoints:

• GET /api/mcp/pending-changes - List pending changes
• POST /api/mcp/pending-changes/{id}/approve - Approve change
• POST /api/mcp/pending-changes/{id}/reject - Reject change

---

Story 11: Core MCP Tools Implementation (3 days) - P0 CRITICAL

Goal: Implement 3 core write operation Tools with Diff Preview

Scope: Implement the following Tools:

1. create_issue - Create new Epic/Story/Task
2. update_status - Change issue status
3. add_comment - Add comment to issue

Each Tool must:

• Generate Diff Preview before execution
• Create PendingChange record
• NOT execute immediately (wait for approval)
• Return pendingChangeId to AI

Acceptance Criteria:

• All 3 Tools generate correct Diff Preview
• PendingChange created with complete diff data
• Tool execution deferred until approval
• AI receives pendingChangeId in response
• Integration tests verify workflow

Tool Interface:

public interface IMcpTool
{
    string Name { get; }
    string Description { get; }
    McpToolInputSchema InputSchema { get; }

    Task<McpToolResult> ExecuteAsync(
        McpToolCall toolCall,
        CancellationToken cancellationToken);
}

Example: CreateIssueTool:

public class CreateIssueTool : IMcpTool
{
    public string Name => "create_issue";
    public string Description => "Create a new issue (Epic/Story/Task)";

    private readonly IDiffPreviewService _diffPreview;
    private readonly IPendingChangeService _pendingChange;

    public async Task<McpToolResult> ExecuteAsync(...)
    {
        // 1. Parse input
        var input = ParseInput(toolCall.Arguments);

        // 2. Generate Diff Preview
        var diff = await _diffPreview.GeneratePreviewAsync(
            null, // no entityId for CREATE
            input,
            "CREATE",
            cancellationToken);

        // 3. Create PendingChange
        var pendingChange = await _pendingChange.CreateAsync(
            Name,
            diff,
            cancellationToken);

        // 4. Return pendingChangeId (do NOT execute yet)
        return new McpToolResult
        {
            Content = new[]
            {
                new McpToolContent
                {
                    Type = "text",
                    Text = $"Change pending approval. ID: {pendingChange.Id}"
                }
            },
            IsError = false
        };
    }
}

Input Schema for create_issue:

{
  "type": "object",
  "properties": {
    "projectId": { "type": "string", "format": "uuid" },
    "title": { "type": "string", "minLength": 1, "maxLength": 200 },
    "description": { "type": "string" },
    "type": { "enum": ["Epic", "Story", "Task", "Bug"] },
    "priority": { "enum": ["Low", "Medium", "High", "Critical"] },
    "assigneeId": { "type": "string", "format": "uuid" },
    "estimatedHours": { "type": "number", "minimum": 0 }
  },
  "required": ["projectId", "title", "type"]
}

---

Story 12: SignalR Real-Time Notifications (1 day) - P0 CRITICAL

Goal: Integrate SignalR to push approval results to AI in real-time

Scope:

• Create McpHub SignalR hub
• Implement PendingChangeApproved event handler
• Push approval/rejection notification via WebSocket
• AI client connection management
• Fallback to polling if WebSocket unavailable

Acceptance Criteria:

• SignalR hub accepts MCP client connections
• Approval notification pushed within 1 second
• Rejection notification includes reason
• Connection authenticated via API Key
• Handles disconnections gracefully

SignalR Hub:

public class McpHub : Hub
{
    public async Task SubscribeToPendingChange(Guid pendingChangeId)
    {
        await Groups.AddToGroupAsync(
            Context.ConnectionId,
            $"pending-change-{pendingChangeId}");
    }

    public async Task UnsubscribeFromPendingChange(Guid pendingChangeId)
    {
        await Groups.RemoveFromGroupAsync(
            Context.ConnectionId,
            $"pending-change-{pendingChangeId}");
    }
}

Event Handler:

public class PendingChangeApprovedEventHandler
    : INotificationHandler<PendingChangeApprovedEvent>
{
    private readonly IHubContext<McpHub> _hubContext;

    public async Task Handle(PendingChangeApprovedEvent e, ...)
    {
        await _hubContext.Clients
            .Group($"pending-change-{e.PendingChangeId}")
            .SendAsync("PendingChangeApproved", new
            {
                PendingChangeId = e.PendingChangeId,
                Status = "Approved",
                Result = e.ExecutionResult,
                Timestamp = DateTime.UtcNow
            });
    }
}

---

Timeline

Week 1-2: Phase 1 - Foundation

• Day 1-3: Story 1 - MCP Protocol Handler
• Day 4-5: Story 2 - API Key Management
• Day 6-7: Story 3 - MCP Domain Layer
• Day 8: Story 4 - Error Handling & Logging

Milestone: MCP infrastructure ready, API Key authentication working

Week 3-4: Phase 2 - Resources

• Day 9-11: Story 5 - Core Resources Implementation
• Day 12: Story 6 - Resource Registration
• Day 13-14: Story 7 - Multi-Tenant Isolation Verification
• Day 15-16: Story 8 - Redis Caching Integration

Milestone: AI can read ColaFlow data via MCP Resources

Week 5-6: Phase 3 - Tools & Diff Preview

• Day 17-18: Story 9 - Diff Preview Service
• Day 19-20: Story 10 - PendingChange Management
• Day 21-23: Story 11 - Core Tools Implementation
• Day 24: Story 12 - SignalR Notifications

Milestone: AI can request write operations (with approval workflow)

---

Definition of Done

Sprint-Level DoD

• All P0 stories completed (Stories 1-12)
• MCP protocol initialize handshake works
• API Key authentication functional
• 5 Resources return correct data with < 200ms latency
• 3 Tools generate Diff Preview correctly
• Approval workflow complete (PendingChange → Approve → Execute)
• SignalR real-time notifications working
• Multi-tenant isolation 100% verified
• Redis caching improves performance by 30%+
• Unit test coverage > 80%
• Integration tests pass
• No CRITICAL security vulnerabilities
• Architecture documentation updated

Story-Level DoD (Per Story)

• Code complete and compiles
• Unit tests written and passing
• Integration tests written and passing
• Code reviewed and approved
• No compiler warnings
• No TODO/FIXME comments
• XML documentation for public APIs
• Follows C# coding standards
• Database migrations created (if applicable)
• Performance tested (if applicable)

---

Success Metrics

Performance Metrics

• API Response Time: < 200ms (P50), < 500ms (P95)
• MCP Protocol Overhead: < 5ms per request
• Cache Hit Rate: > 80% for hot Resources
• Throughput: > 100 requests/second per instance

Quality Metrics

• Unit Test Coverage: > 80%
• Integration Test Coverage: > 70%
• Security Vulnerabilities: 0 CRITICAL, 0 HIGH
• Code Duplication: < 5%

Functional Metrics

• Resources Implemented: 5/5 (100%)
• Tools Implemented: 3/3 (100%)
• Multi-Tenant Isolation: 100% verified
• Diff Preview Accuracy: 100% (all changed fields detected)

---

Dependencies

Prerequisites

• ✅ M1 Core Features 82% complete (Sprint 1-4)
• ✅ ProjectManagement Module production-ready
• ✅ SignalR infrastructure complete (Day 17)
• ✅ Multi-tenant security verified (Day 14-16)
• ✅ Audit Log system available (Day 14 design complete)

Technical Stack

• .NET 9 (ASP.NET Core)
• PostgreSQL 15+
• Redis 7+
• EF Core 9
• MediatR (CQRS)
• SignalR
• BCrypt.Net
• Serilog

External Dependencies

• MCP Protocol Specification (JSON-RPC 2.0)
• Claude Desktop / ChatGPT MCP clients (for testing)

---

Risks & Mitigation

Risk ID	Description	Impact	Probability	Mitigation	Owner
RISK-001	MCP protocol specification changes	High	Medium	Version control, quick adaptation	Architect
RISK-002	Performance bottleneck (high concurrency)	Medium	Medium	Redis caching, horizontal scaling	Backend Lead
RISK-003	API Key security breach	High	Low	BCrypt hashing, IP whitelist, rate limiting	Security Lead
RISK-004	Diff Preview inaccurate for complex objects	Medium	Medium	Comprehensive testing, JSON diff library	Backend Dev
RISK-005	SignalR scalability issues	Medium	Low	Use Redis backplane for multi-instance	Backend Lead
RISK-006	Multi-tenant data leak	Critical	Very Low	100% test coverage, security audit	QA Lead

---

Architecture Decisions

AD-001: Custom .NET MCP Implementation (Not Node.js SDK)

Decision: Implement MCP protocol natively in .NET 9 instead of using official Node.js SDK

Rationale:

• Native integration with ASP.NET Core backend
• Better performance (especially concurrency)
• No Node.js deployment dependency
• Team expertise in .NET
• Type safety with C#

Alternatives Considered:

• Official Node.js MCP SDK (rejected: extra runtime, worse performance)
• Hybrid approach with Node.js bridge (rejected: added complexity)

AD-002: Diff Preview Approval Workflow

Decision: All AI write operations require human approval via Diff Preview

Rationale:

• Security: Prevent AI mistakes
• Transparency: Users see what will change
• Compliance: Audit trail required
• Trust: Build user confidence in AI

Alternatives Considered:

• Auto-approval for low-risk operations (deferred to Phase 4)
• No preview, direct execution (rejected: too risky)

AD-003: Direct Service Integration (Not HTTP API)

Decision: MCP Server calls existing CQRS commands directly via MediatR

Rationale:

• Zero network latency
• Shared transaction context
• Reuse existing business logic
• Simpler deployment (same process)

Alternatives Considered:

• HTTP API calls (deferred to M4 if services split)

AD-004: PostgreSQL JSONB for Diff Storage

Decision: Store Diff Preview data in PostgreSQL JSONB column

Rationale:

• Flexible schema for different entity types
• Efficient querying with JSONB operators
• No additional storage system needed
• Transactional consistency

Alternatives Considered:

• MongoDB (rejected: adds new dependency)
• Separate diff tables per entity (rejected: too complex)

---

Technical Debt

Known Limitations (To Address Post-Sprint)

1. No IP Whitelist Enforcement (Phase 1)

   • Debt: API Key validation doesn't check IP whitelist
   • Plan: Add in Phase 4 (Approval Workflow)

2. Simple Cache Invalidation (Phase 2)

   • Debt: Cache invalidation is time-based (TTL), not event-driven
   • Plan: Add domain event listeners in Phase 5

3. No Advanced Query Language (Phase 2)

   • Debt: issues.search uses simple filters, not JQL
   • Plan: Add JQL-like query parser in M3

4. No Rate Limiting (Phase 1)

   • Debt: API Key has no rate limits
   • Plan: Add rate limiting middleware in Phase 6

5. Hardcoded Approval Rules (Phase 3)

   • Debt: All Tools require approval (no config)
   • Plan: Add configurable approval rules in Phase 7

---

Testing Strategy

Unit Tests (> 80% Coverage)

• Domain entities and value objects
• CQRS command/query handlers
• Diff Preview generation logic
• API Key validation logic
• MCP protocol parsing

Integration Tests (> 70% Coverage)

• End-to-end MCP request/response flow
• Database operations (EF Core repositories)
• Multi-tenant isolation verification
• Cache hit/miss scenarios
• SignalR notifications

Performance Tests

• Concurrent API requests (100 req/s)
• Cache performance benchmarks
• Database query performance
• MCP protocol overhead

Security Tests

• Cross-tenant access attempts
• API Key brute force
• SQL injection attempts
• JWT token validation

---

Related Documents

Architecture Documents

• MCP Server Architecture - Complete 1,867-line design doc
• MCP Suggestions - Architect's suggestions and analysis

Planning Documents

• Product Roadmap - M2 section
• Sprint 1 - Frontend Integration
• Sprint 2 - M1 Backend Features
• Sprint 3 - Frontend Code Quality
• Sprint 4 - Story Management & UX Enhancement

Technical References

• ProjectManagement Module
• Identity & RBAC Module
• SignalR Hubs

---

Notes

Why This Sprint Matters

For Product:

• AI Integration Foundation: Enables ColaFlow to become AI-native
• Market Differentiation: MCP support is cutting-edge (few competitors)
• M2 Milestone Progress: 50% of M2 completed after this Sprint

For Users:

• Natural Language PM: Talk to AI to manage projects
• 50% Time Savings: AI automates repetitive tasks
• Safe AI Operations: Every change previewed and approved

For Development:

• Clean Architecture: Solid foundation for M3-M5
• Reusable Patterns: Diff Preview, approval workflow reusable
• Quality Focus: High test coverage, security-first design

Phase 4-7 Preview (Not in This Sprint)

Phase 4: Approval Workflow (Week 7-8)

• Frontend approval UI
• Audit log integration
• Advanced approval rules

Phase 5: Prompts & Integration (Week 9-10)

• 2 core Prompts (generate_prd, split_epic_to_stories)
• Claude Desktop integration PoC
• End-to-end testing

Phase 6: Testing & Hardening (Week 11-12)

• Performance optimization
• Security audit
• Production readiness

Phase 7: Documentation & PoC (Week 13-16)

• Complete API documentation
• Video demo
• Internal training

---

Sprint Retrospective Questions

What Went Well?

• Clean architecture enabled fast development?
• Domain-driven design reduced bugs?
• Test coverage caught issues early?

What Can Improve?

• Integration testing too slow?
• Domain events too complex?
• Diff Preview edge cases?

Action Items for Next Sprint

• Optimize integration test performance
• Simplify domain event handlers
• Add more Diff Preview test cases

---

Created: 2025-11-06 by Product Manager Agent Next Review: 2025-12-04 (mid-sprint checkpoint, Week 3) Sprint Duration: 8 weeks (40 working days) Target Completion: 2026-01-22 Minimum Viable: 2026-01-08 (Phase 1-2 only, 6 weeks)