ColaFlow/docs/plans/sprint_5.md

---
sprint_id: sprint_5
milestone: M2
status: not_started
created_date: 2025-11-06
start_date: 2025-11-27
target_end_date: 2026-01-22
duration_weeks: 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](sprint_5_story_1.md) - MCP Protocol Handler Implementation - `not_started` - **P0 Critical** - 3 days
- [ ] [story_2](sprint_5_story_2.md) - API Key Management System - `not_started` - **P0 Critical** - 2 days
- [ ] [story_3](sprint_5_story_3.md) - MCP Domain Layer Design - `not_started` - **P0 Critical** - 2 days
- [ ] [story_4](sprint_5_story_4.md) - Error Handling & Logging - `not_started` - **P0 Critical** - 1 day

### Phase 2 Stories (Week 3-4)
- [ ] [story_5](sprint_5_story_5.md) - Core MCP Resources Implementation - `not_started` - **P0 Critical** - 3 days
- [ ] [story_6](sprint_5_story_6.md) - Resource Registration & Discovery - `not_started` - **P0 Critical** - 1 day
- [ ] [story_7](sprint_5_story_7.md) - Multi-Tenant Isolation Verification - `not_started` - **P0 Critical** - 2 days
- [ ] [story_8](sprint_5_story_8.md) - Redis Caching Integration - `not_started` - **P1 High** - 2 days

### Phase 3 Stories (Week 5-6)
- [ ] [story_9](sprint_5_story_9.md) - Diff Preview Service Implementation - `not_started` - **P0 Critical** - 2 days
- [ ] [story_10](sprint_5_story_10.md) - PendingChange Management - `not_started` - **P0 Critical** - 2 days
- [ ] [story_11](sprint_5_story_11.md) - Core MCP Tools Implementation - `not_started` - **P0 Critical** - 3 days
- [ ] [story_12](sprint_5_story_12.md) - 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](sprint_5_story_0.md) - **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](sprint_5_story_13.md) - MCP SDK Foundation & Proof of Concept - `not_started` - **P0 Critical** - 10 days

#### Phase 2: Tool Migration (Week 3-4)
- [ ] [story_14](sprint_5_story_14.md) - Tool Migration to SDK Attributes - `not_started` - **P0 Critical** - 10 days

#### Phase 3: Resource Migration (Week 5)
- [ ] [story_15](sprint_5_story_15.md) - Resource Migration to SDK Attributes - `not_started` - **P0 Critical** - 5 days

#### Phase 4: Transport Layer (Week 6)
- [ ] [story_16](sprint_5_story_16.md) - Transport Layer Migration to SDK - `not_started` - **P0 Critical** - 5 days

#### Phase 5: Testing & Optimization (Week 7-8)
- [ ] [story_17](sprint_5_story_17.md) - 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**:
```csharp
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**:
```sql
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)
```csharp
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)
```csharp
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)
```csharp
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**:
```csharp
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**:
```csharp
public interface IMcpResource
{
    string Uri { get; }
    string Name { get; }
    string Description { get; }
    string MimeType { get; }

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

**Example Implementation**:
```csharp
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**:
```json
{
  "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**:
```csharp
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**:
```csharp
public interface IDiffPreviewService
{
    Task<DiffPreview> GeneratePreviewAsync<TEntity>(
        Guid? entityId,
        TEntity afterData,
        string operation,
        CancellationToken cancellationToken);
}
```

**Diff Output Example**:
```json
{
  "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**:
```sql
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**:
```csharp
public interface IMcpTool
{
    string Name { get; }
    string Description { get; }
    McpToolInputSchema InputSchema { get; }

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

**Example: CreateIssueTool**:
```csharp
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**:
```json
{
  "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**:
```csharp
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**:
```csharp
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](../architecture/mcp-server-architecture.md) - Complete 1,867-line design doc
- [MCP Suggestions](../mcp-suggestion.md) - Architect's suggestions and analysis

### Planning Documents
- [Product Roadmap](../../product.md) - M2 section
- [Sprint 1](sprint_1.md) - Frontend Integration
- [Sprint 2](sprint_2.md) - M1 Backend Features
- [Sprint 3](sprint_3.md) - Frontend Code Quality
- [Sprint 4](sprint_4.md) - Story Management & UX Enhancement

### Technical References
- [ProjectManagement Module](../../colaflow-api/src/ColaFlow.Modules.ProjectManagement/)
- [Identity & RBAC Module](../../colaflow-api/src/ColaFlow.Modules.Identity/)
- [SignalR Hubs](../../colaflow-api/src/ColaFlow.Infrastructure.SignalR/)

---

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