ColaFlow/docs/stories/sprint_5/story_5_5.md

story_id, sprint_id, phase, status, priority, story_points, assignee, estimated_days, created_date, dependencies

story_id	sprint_id	phase	status	priority	story_points	assignee	estimated_days	created_date	dependencies
story_5_5	sprint_5	Phase 2 - Resources	not_started	P0	8	backend	3	2025-11-06	story_5_1 story_5_2 story_5_3

Story 5.5: Core MCP Resources Implementation

Phase: Phase 2 - Resources (Week 3-4) Priority: P0 CRITICAL Estimated Effort: 8 Story Points (3 days)

User Story

As an AI Agent (Claude, ChatGPT) I want to read ColaFlow project data through MCP Resources So that I can understand project context and answer user questions

Business Value

This is the first user-facing MCP feature. AI agents can now READ ColaFlow data, enabling:

• AI-powered project queries ("Show me high-priority bugs")
• Natural language reporting ("What's the status of Sprint 5?")
• Context-aware AI assistance ("Who's assigned to this Story?")

Impact:

• Enables 50% of M2 user stories (read-only AI features)
• Foundation for future write operations (Phase 3)
• Demonstrates MCP Server working end-to-end

Acceptance Criteria

AC1: Projects Resources

• colaflow://projects.list - List all projects
• colaflow://projects.get/{id} - Get project details
• Multi-tenant isolation (only current tenant's projects)
• Response time < 200ms

AC2: Issues Resources

• colaflow://issues.search - Search issues with filters
• colaflow://issues.get/{id} - Get issue details (Epic/Story/Task)
• Query parameters: status, priority, assignee, type, project
• Pagination support (limit, offset)
• Response time < 200ms

AC3: Sprints Resources

• colaflow://sprints.current - Get current active Sprint
• colaflow://sprints.get/{id} - Get Sprint details
• Include Sprint statistics (total issues, completed, in progress)

AC4: Users Resource

• colaflow://users.list - List team members
• Filter by project, role
• Include user profile data (name, email, avatar)

AC5: Resource Registration

• All Resources auto-register at startup
• resources/list returns complete catalog
• Each Resource has URI, name, description, MIME type

AC6: Testing

• Unit tests for each Resource (> 80% coverage)
• Integration tests for Resource endpoints
• Multi-tenant isolation tests
• Performance tests (< 200ms response time)

Technical Design

Resource Interface

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

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

public class McpResourceRequest
{
    public string Uri { get; set; }
    public Dictionary<string, string> Params { get; set; } = new();
}

public class McpResourceContent
{
    public string Uri { get; set; }
    public string MimeType { get; set; }
    public string Text { get; set; } // JSON serialized data
}

Example: ProjectsListResource

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;
    private readonly ILogger<ProjectsListResource> _logger;

    public async Task<McpResourceContent> GetContentAsync(
        McpResourceRequest request,
        CancellationToken cancellationToken)
    {
        var tenantId = _tenantContext.CurrentTenantId;

        _logger.LogDebug(
            "Fetching projects list for tenant {TenantId}",
            tenantId);

        var projects = await _projectRepo.GetAllAsync(
            tenantId,
            cancellationToken);

        var projectDtos = projects.Select(p => new
        {
            id = p.Id,
            name = p.Name,
            key = p.Key,
            status = p.Status.ToString(),
            owner = new { id = p.OwnerId, name = p.Owner?.Name },
            issueCount = p.IssueCount,
            memberCount = p.MemberCount,
            createdAt = p.CreatedAt
        });

        var json = JsonSerializer.Serialize(new { projects = projectDtos });

        return new McpResourceContent
        {
            Uri = Uri,
            MimeType = MimeType,
            Text = json
        };
    }
}

Resource Catalog Response

{
  "resources": [
    {
      "uri": "colaflow://projects.list",
      "name": "Projects List",
      "description": "List all projects in current tenant",
      "mimeType": "application/json"
    },
    {
      "uri": "colaflow://projects.get/{id}",
      "name": "Project Details",
      "description": "Get detailed information about a project",
      "mimeType": "application/json"
    },
    {
      "uri": "colaflow://issues.search",
      "name": "Issues Search",
      "description": "Search issues with filters (status, priority, assignee, etc.)",
      "mimeType": "application/json"
    },
    {
      "uri": "colaflow://issues.get/{id}",
      "name": "Issue Details",
      "description": "Get detailed information about an issue (Epic/Story/Task)",
      "mimeType": "application/json"
    },
    {
      "uri": "colaflow://sprints.current",
      "name": "Current Sprint",
      "description": "Get the currently active Sprint",
      "mimeType": "application/json"
    },
    {
      "uri": "colaflow://users.list",
      "name": "Team Members",
      "description": "List all team members in current tenant",
      "mimeType": "application/json"
    }
  ]
}

Tasks

Task 1: Resource Infrastructure (4 hours)

• Create IMcpResource interface
• Create McpResourceRequest, McpResourceContent DTOs
• Create IMcpResourceDispatcher interface
• Implement McpResourceDispatcher (route requests to Resources)
• Update McpProtocolHandler to call dispatcher

Files to Create:

• ColaFlow.Modules.Mcp/Contracts/IMcpResource.cs
• ColaFlow.Modules.Mcp/DTOs/McpResourceRequest.cs
• ColaFlow.Modules.Mcp/DTOs/McpResourceContent.cs
• ColaFlow.Modules.Mcp/Contracts/IMcpResourceDispatcher.cs
• ColaFlow.Modules.Mcp/Services/McpResourceDispatcher.cs

Task 2: ProjectsListResource (3 hours)

• Implement ProjectsListResource class
• Query ProjectManagement repository
• Apply TenantId filter
• Serialize to JSON
• Unit tests

Files to Create:

• ColaFlow.Modules.Mcp/Resources/ProjectsListResource.cs
• ColaFlow.Modules.Mcp.Tests/Resources/ProjectsListResourceTests.cs

Task 3: ProjectsGetResource (2 hours)

• Implement ProjectsGetResource class
• Extract {id} from URI
• Query project by ID + TenantId
• Return 404 if not found or wrong tenant
• Unit tests

Files to Create:

• ColaFlow.Modules.Mcp/Resources/ProjectsGetResource.cs
• ColaFlow.Modules.Mcp.Tests/Resources/ProjectsGetResourceTests.cs

Task 4: IssuesSearchResource (4 hours)

• Implement IssuesSearchResource class
• Parse query params (status, priority, assignee, type, project)
• Build dynamic query (EF Core)
• Apply pagination (limit, offset)
• Apply TenantId filter
• Unit tests

Files to Create:

• ColaFlow.Modules.Mcp/Resources/IssuesSearchResource.cs
• ColaFlow.Modules.Mcp.Tests/Resources/IssuesSearchResourceTests.cs

Task 5: IssuesGetResource (3 hours)

• Implement IssuesGetResource class
• Support Epic, Story, WorkTask lookup
• Return full issue details (including parent/children)
• Apply TenantId filter
• Unit tests

Files to Create:

• ColaFlow.Modules.Mcp/Resources/IssuesGetResource.cs
• ColaFlow.Modules.Mcp.Tests/Resources/IssuesGetResourceTests.cs

Task 6: SprintsCurrentResource (2 hours)

• Implement SprintsCurrentResource class
• Query active Sprint (status = InProgress)
• Include Sprint statistics
• Apply TenantId filter
• Unit tests

Files to Create:

• ColaFlow.Modules.Mcp/Resources/SprintsCurrentResource.cs
• ColaFlow.Modules.Mcp.Tests/Resources/SprintsCurrentResourceTests.cs

Task 7: UsersListResource (2 hours)

• Implement UsersListResource class
• Query users in current tenant
• Filter by project (optional)
• Include profile data (name, email, avatar URL)
• Unit tests

Files to Create:

• ColaFlow.Modules.Mcp/Resources/UsersListResource.cs
• ColaFlow.Modules.Mcp.Tests/Resources/UsersListResourceTests.cs

Task 8: Resource Registration (2 hours)

• Create IMcpRegistry interface
• Implement auto-discovery via Reflection
• Register all Resources at startup
• Implement resources/list method handler

Files to Create:

• ColaFlow.Modules.Mcp/Contracts/IMcpRegistry.cs
• ColaFlow.Modules.Mcp/Services/McpRegistry.cs

Task 9: Integration Tests (4 hours)

• Test end-to-end Resource requests
• Test multi-tenant isolation (Tenant A cannot read Tenant B data)
• Test pagination
• Test query filters
• Test performance (< 200ms)

Files to Create:

• ColaFlow.Modules.Mcp.Tests/Integration/McpResourcesIntegrationTests.cs

Testing Strategy

Unit Tests (> 80% coverage)

• Each Resource class independently
• Query building logic
• JSON serialization
• Error handling (not found, invalid params)

Integration Tests

• End-to-end Resource requests
• Multi-tenant isolation verification
• Pagination correctness
• Performance benchmarks

Manual Testing with Claude Desktop

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test projects.list
mcp-inspector colaflow://projects.list

# Test issues.search with filters
mcp-inspector colaflow://issues.search?status=InProgress&priority=High

# Test sprints.current
mcp-inspector colaflow://sprints.current

Dependencies

Prerequisites:

• Story 5.1 (MCP Protocol Handler) - Resource routing
• Story 5.2 (API Key Management) - Authentication
• Story 5.3 (MCP Domain Layer) - Domain entities
• M1 ProjectManagement Module - Data source

Blocks:

• Story 5.11 (Core MCP Tools) - Tools depend on Resources working

Risks & Mitigation

Risk	Impact	Probability	Mitigation
Performance slow (> 200ms)	Medium	Medium	Redis caching (Story 5.8), database indexes
Multi-tenant leak	High	Low	100% test coverage, Global Query Filters
Query complexity	Medium	Medium	Limit query params, use IQueryable
JSON serialization bugs	Low	Low	Unit tests, use System.Text.Json

Definition of Done

• Code compiles without warnings
• All 6 Resources implemented and working
• Unit test coverage > 80%
• Integration tests passing
• Multi-tenant isolation verified (100%)
• Performance < 200ms (P95)
• Code reviewed and approved
• XML documentation for public APIs
• Resources registered and discoverable (resources/list)

Notes

Why This Story Matters

• First AI Integration: AI can now read ColaFlow data
• Foundation for M2: 50% of M2 features are read-only
• User Value: Enables natural language project queries
• Milestone Demo: Demonstrates MCP Server working

Key Design Decisions

1. URI Scheme: colaflow:// custom protocol
2. JSON Responses: All Resources return JSON
3. Pagination: Limit/offset for large result sets
4. Filtering: Query params for fine-grained control
5. Multi-Tenant: TenantContext ensures data isolation

Performance Optimization

• Use AsNoTracking() for read-only queries (30% faster)
• Add database indexes on commonly filtered columns
• Implement Redis caching (Story 5.8) for hot Resources
• Limit pagination size (max 100 items)

Resource URI Design Guidelines

• Use descriptive names: projects.list, issues.search
• Use {id} for parameterized URIs: projects.get/{id}
• Use query params for filters: issues.search?status=InProgress
• Keep URIs stable (versioning if needed)

Reference Materials

• MCP Resources Spec: https://modelcontextprotocol.io/docs/concepts/resources
• Sprint 5 Plan: docs/plans/sprint_5.md
• Architecture Design: docs/M2-MCP-SERVER-ARCHITECTURE.md