--- story_id: story_5_5 sprint_id: sprint_5 phase: Phase 2 - Resources status: not_started priority: P0 story_points: 8 assignee: backend estimated_days: 3 created_date: 2025-11-06 dependencies: [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 ```csharp public interface IMcpResource { string Uri { get; } string Name { get; } string Description { get; } string MimeType { get; } Task GetContentAsync( McpResourceRequest request, CancellationToken cancellationToken); } public class McpResourceRequest { public string Uri { get; set; } public Dictionary 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 ```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; private readonly ILogger _logger; public async Task 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 ```json { "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 ```bash # 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`