kai/ColaFlow
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
b11c6447b55ff247e705b6254c166f6f4ca44fee
ColaFlow/docs/stories/sprint_5/README.md
Yaojia Wang 48a8431e4f feat(backend): Implement MCP Protocol Handler (Story 5.1) 
Implemented JSON-RPC 2.0 protocol handler for MCP communication, enabling AI agents to communicate with ColaFlow using the Model Context Protocol.

**Implementation:**
- JSON-RPC 2.0 data models (Request, Response, Error, ErrorCode)
- MCP protocol models (Initialize, Capabilities, ClientInfo, ServerInfo)
- McpProtocolHandler with method routing and error handling
- Method handlers: initialize, resources/list, tools/list, tools/call
- ASP.NET Core middleware for /mcp endpoint
- Service registration and dependency injection setup

**Testing:**
- 28 unit tests covering protocol parsing, validation, and error handling
- Integration tests for initialize handshake and error responses
- All tests passing with >80% coverage

**Changes:**
- Created ColaFlow.Modules.Mcp.Contracts project
- Created ColaFlow.Modules.Mcp.Domain project
- Created ColaFlow.Modules.Mcp.Application project
- Created ColaFlow.Modules.Mcp.Infrastructure project
- Created ColaFlow.Modules.Mcp.Tests project
- Registered MCP module in ColaFlow.API Program.cs
- Added /mcp endpoint via middleware

**Acceptance Criteria Met:**
✅ JSON-RPC 2.0 messages correctly parsed
✅ Request validation (jsonrpc: "2.0", method, params, id)
✅ Error responses conform to JSON-RPC 2.0 spec
✅ Invalid requests return proper error codes (-32700, -32600, -32601, -32602)
✅ MCP initialize method implemented
✅ Server capabilities returned (resources, tools, prompts)
✅ Protocol version negotiation works (1.0)
✅ Request routing to method handlers
✅ Unit test coverage > 80%
✅ All tests passing

**Story**: docs/stories/sprint_5/story_5_1.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-07 19:38:34 +01:00

291 lines
9.8 KiB
Markdown
Raw Blame History

# Sprint 5 Stories - MCP Server Foundation
**Sprint**: Sprint 5
**Milestone**: M2 - MCP Server Implementation
**Duration**: 8 weeks (40 working days)
**Created**: 2025-11-06
**Total Stories**: 12
**Total Story Points**: 63
---
## Overview
This directory contains detailed Story documents for Sprint 5: MCP Server Foundation (Phase 1-3). These Stories establish the foundational infrastructure for AI integration through the Model Context Protocol (MCP).
**Sprint 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.
---
## Phase 1: Foundation (Week 1-2)
**Goal**: Establish MCP protocol infrastructure, API Key authentication, and basic error handling.
| Story ID | Title | Priority | Story Points | Est. Days | Dependencies |
|----------|-------|----------|--------------|-----------|--------------|
| [story_5_1](story_5_1.md) | MCP Protocol Handler Implementation | P0 | 8 | 3 | - |
| [story_5_2](story_5_2.md) | API Key Management System | P0 | 5 | 2 | - |
| [story_5_3](story_5_3.md) | MCP Domain Layer Design | P0 | 5 | 2 | - |
| [story_5_4](story_5_4.md) | Error Handling & Logging | P0 | 3 | 1 | story_5_1 |
**Phase 1 Total**: 21 Story Points (8 days)
**Milestone**: MCP infrastructure ready, API Key authentication working
---
## Phase 2: Resources (Week 3-4)
**Goal**: Implement read-only data exposure (5 core Resources), multi-tenant isolation, Redis caching.
| Story ID | Title | Priority | Story Points | Est. Days | Dependencies |
|----------|-------|----------|--------------|-----------|--------------|
| [story_5_5](story_5_5.md) | Core MCP Resources Implementation | P0 | 8 | 3 | story_5_1, story_5_2, story_5_3 |
| [story_5_6](story_5_6.md) | Resource Registration & Discovery | P0 | 3 | 1 | story_5_5 |
| [story_5_7](story_5_7.md) | Multi-Tenant Isolation Verification | P0 | 5 | 2 | story_5_5, story_5_2 |
| [story_5_8](story_5_8.md) | Redis Caching Integration | P1 | 5 | 2 | story_5_5 |
**Phase 2 Total**: 21 Story Points (8 days)
**Milestone**: AI can read ColaFlow data via MCP Resources
---
## Phase 3: Tools & Diff Preview (Week 5-6)
**Goal**: Implement write operations (3 core Tools), build Diff Preview mechanism, SignalR real-time notifications.
| Story ID | Title | Priority | Story Points | Est. Days | Dependencies |
|----------|-------|----------|--------------|-----------|--------------|
| [story_5_9](story_5_9.md) | Diff Preview Service Implementation | P0 | 5 | 2 | story_5_3 |
| [story_5_10](story_5_10.md) | PendingChange Management | P0 | 5 | 2 | story_5_3, story_5_9 |
| [story_5_11](story_5_11.md) | Core MCP Tools Implementation | P0 | 8 | 3 | story_5_1, story_5_9, story_5_10 |
| [story_5_12](story_5_12.md) | SignalR Real-Time Notifications | P0 | 3 | 1 | story_5_10 |
**Phase 3 Total**: 21 Story Points (8 days)
**Milestone**: AI can request write operations (with approval workflow)
---
## Story Summary
### By Priority
- **P0 (Critical)**: 11 Stories, 58 Story Points
- **P1 (High)**: 1 Story, 5 Story Points
### By Phase
- **Phase 1 (Foundation)**: 4 Stories, 21 Story Points
- **Phase 2 (Resources)**: 4 Stories, 21 Story Points
- **Phase 3 (Tools & Diff Preview)**: 4 Stories, 21 Story Points
### Dependency Graph
```
Phase 1:
story_5_1 (Protocol Handler) ──┐
story_5_2 (API Key) ├──> story_5_5 (Resources) ──> story_5_6 (Registry)
story_5_3 (Domain Layer) ──────┤ ├──> story_5_7 (Multi-Tenant)
│ └──> story_5_8 (Redis Cache)
story_5_1 ──> story_5_4 (Error Handling)
Phase 2 → Phase 3:
story_5_3 ──> story_5_9 (Diff Preview) ──> story_5_10 (PendingChange) ──> story_5_11 (Tools)
└──> story_5_12 (SignalR)
story_5_1 ──────────────────────────────────────────────────────────────> story_5_11
```
---
## Key Deliverables
### Phase 1: Foundation
- ✅ JSON-RPC 2.0 protocol handler
- ✅ MCP initialize handshake
- ✅ API Key authentication (BCrypt hashing)
- ✅ Domain entities (McpApiKey, PendingChange, DiffPreview)
- ✅ Structured logging (Serilog)
- ✅ Exception handling
### Phase 2: Resources
- ✅ 6 MCP Resources (projects.list, projects.get, issues.search, issues.get, sprints.current, users.list)
- ✅ Resource registration and discovery
- ✅ Multi-tenant isolation (100% verified)
- ✅ Redis caching (30-50% performance improvement)
### Phase 3: Tools & Diff Preview
- ✅ 3 MCP Tools (create_issue, update_status, add_comment)
- ✅ Diff Preview service (CREATE, UPDATE, DELETE)
- ✅ PendingChange approval workflow
- ✅ SignalR real-time notifications
---
## Definition of Done (Sprint-Level)
### Functional
- [ ] 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
### Quality
- [ ] Multi-tenant isolation 100% verified
- [ ] Redis caching improves performance by 30%+
- [ ] Unit test coverage > 80%
- [ ] Integration tests pass
- [ ] No CRITICAL security vulnerabilities
### Documentation
- [ ] Architecture documentation updated
- [ ] API documentation (Swagger)
- [ ] Integration guide for AI clients
---
## 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**: 6/6 (100%)
- **Tools Implemented**: 3/3 (100%)
- **Multi-Tenant Isolation**: 100% verified
- **Diff Preview Accuracy**: 100% (all changed fields detected)
---
## Risk Register
### Critical Risks
| Risk ID | Description | Mitigation | Owner | Story |
|---------|-------------|------------|-------|-------|
| RISK-001 | Multi-tenant data leak | 100% test coverage, security audit | Backend | story_5_7 |
| RISK-002 | API Key security breach | BCrypt hashing, IP whitelist, rate limiting | Backend | story_5_2 |
| RISK-003 | Diff Preview inaccurate | Comprehensive testing, JSON diff library | Backend | story_5_9 |
### High Risks
| Risk ID | Description | Mitigation | Owner | Story |
|---------|-------------|------------|-------|-------|
| RISK-004 | MCP protocol changes | Version control, quick adaptation | Architect | story_5_1 |
| RISK-005 | Performance bottleneck | Redis caching, horizontal scaling | Backend | story_5_8 |
| RISK-006 | SignalR scalability | Redis backplane for multi-instance | Backend | story_5_12 |
---
## Technical Stack
### Backend
- .NET 9 (ASP.NET Core)
- PostgreSQL 15+
- Redis 7+
- EF Core 9
- MediatR (CQRS)
- SignalR
- BCrypt.Net
- Serilog
### Testing
- xUnit
- Moq
- FluentAssertions
- Integration Tests (EF Core In-Memory)
---
## Sprint 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
### 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
### 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
---
## How to Use These Stories
### For Backend Developers
1. Read Story document thoroughly
2. Understand acceptance criteria
3. Follow task breakdown (estimated hours)
4. Write tests first (TDD recommended)
5. Implement feature
6. Submit PR with all DoD items checked
### For QA Engineers
1. Review acceptance criteria
2. Prepare test scenarios
3. Verify unit test coverage
4. Execute integration tests
5. Report bugs with Story ID reference
### For Product Manager
1. Track Story status (not_started, in_progress, completed)
2. Monitor dependencies
3. Update Sprint progress
4. Coordinate Story sequencing
---
## Related Documents
### Planning Documents
- [Sprint 5 Plan](../../plans/sprint_5.md) - Sprint overview and timeline
- [Product Roadmap](../../../product.md) - M2 section
### Architecture Documents
- [MCP Server Architecture](../../M2-MCP-SERVER-ARCHITECTURE.md) - Complete 73KB design doc
- [MCP Suggestions](../../mcp-suggestion.md) - Architect's analysis
### Technical References
- [MCP Protocol Specification](https://modelcontextprotocol.io/docs)
- [JSON-RPC 2.0 Spec](https://www.jsonrpc.org/specification)
---
## Notes
### Why Sprint 5 Matters
- **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
- **User Value**: AI automates 50% of manual project management work
### What Makes This Sprint Unique
- **Security First**: Multi-tenant isolation is P0
- **Diff Preview**: Unique safety mechanism (not in competitors)
- **Human-in-the-Loop**: AI proposes, human approves
- **Real-Time**: SignalR notifications complete the loop
---
**Created**: 2025-11-06 by Product Manager Agent
**Last Updated**: 2025-11-06
**Next Review**: Sprint Planning Meeting (2025-11-27)
Reference in New Issue View Git Blame Copy Permalink