Clean up
This commit is contained in:
Yaojia Wang
@@ -76,6 +76,80 @@ ColaFlow M1 core features are 82% complete (Day 17). M2 phase focuses on impleme
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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
|
||||
|
||||
580
docs/plans/sprint_5_story_0.md
Normal file
580
docs/plans/sprint_5_story_0.md
Normal file
@@ -0,0 +1,580 @@
|
||||
---
|
||||
story_id: story_0
|
||||
sprint_id: sprint_5
|
||||
status: not_started
|
||||
priority: P0
|
||||
assignee: backend
|
||||
created_date: 2025-11-09
|
||||
story_type: epic
|
||||
estimated_weeks: 8
|
||||
---
|
||||
|
||||
# Story 0 (EPIC): Integrate Microsoft .NET MCP SDK
|
||||
|
||||
**Type**: Epic / Feature Story
|
||||
**Priority**: P0 - Critical Infrastructure Improvement
|
||||
**Estimated Effort**: 8 weeks (40 working days)
|
||||
|
||||
## Epic Goal
|
||||
|
||||
Migrate ColaFlow from custom MCP implementation to Microsoft's official .NET MCP SDK using a hybrid architecture approach. The SDK will handle protocol layer, Tool/Resource registration, and transport, while ColaFlow retains its unique business logic (Diff Preview, multi-tenant isolation, Pending Changes).
|
||||
|
||||
## Business Value
|
||||
|
||||
### Why This Matters
|
||||
|
||||
1. **Code Reduction**: 60-70% less boilerplate code (protocol parsing, JSON-RPC, handshake)
|
||||
2. **Performance Gain**: 30-40% faster response times (SDK optimizations)
|
||||
3. **Maintenance**: Microsoft-maintained protocol updates (no manual updates)
|
||||
4. **Standard Compliance**: 100% MCP specification compliance guaranteed
|
||||
5. **Developer Experience**: Attribute-based registration (cleaner, more intuitive)
|
||||
|
||||
### Success Metrics
|
||||
|
||||
- **Code Reduction**: Remove 500-700 lines of custom protocol code
|
||||
- **Performance**: ≥ 20% response time improvement
|
||||
- **Test Coverage**: Maintain ≥ 80% coverage
|
||||
- **Zero Breaking Changes**: All existing MCP clients work without changes
|
||||
- **SDK Integration**: 100% of Tools and Resources migrated
|
||||
|
||||
## Research Context
|
||||
|
||||
**Research Report**: `docs/research/mcp-sdk-integration-research.md`
|
||||
|
||||
Key findings from research team:
|
||||
- **SDK Maturity**: Production-ready (v1.0+), 4000+ GitHub stars
|
||||
- **Architecture Fit**: Excellent fit with ColaFlow's Clean Architecture
|
||||
- **Attribute System**: `[McpTool]`, `[McpResource]` attributes simplify registration
|
||||
- **Transport Options**: stdio (CLI), HTTP/SSE (Server), WebSocket (future)
|
||||
- **Performance**: Faster JSON parsing, optimized middleware
|
||||
- **Compatibility**: Supports Claude Desktop, Continue, Cline
|
||||
|
||||
## Hybrid Architecture Strategy
|
||||
|
||||
### What SDK Handles (Replace Custom Code)
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────┐
|
||||
│ Microsoft .NET MCP SDK │
|
||||
├──────────────────────────────────────┤
|
||||
│ ✅ Protocol Layer │
|
||||
│ - JSON-RPC 2.0 parsing │
|
||||
│ - MCP handshake (initialize) │
|
||||
│ - Request/response routing │
|
||||
│ - Error handling │
|
||||
│ │
|
||||
│ ✅ Transport Layer │
|
||||
│ - stdio (Standard In/Out) │
|
||||
│ - HTTP/SSE (Server-Sent Events) │
|
||||
│ - WebSocket (future) │
|
||||
│ │
|
||||
│ ✅ Registration System │
|
||||
│ - Attribute-based discovery │
|
||||
│ - Tool/Resource/Prompt catalog │
|
||||
│ - Schema validation │
|
||||
└──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### What ColaFlow Keeps (Business Logic)
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────┐
|
||||
│ ColaFlow Business Layer │
|
||||
├──────────────────────────────────────┤
|
||||
│ 🔒 Security & Multi-Tenant │
|
||||
│ - TenantContext extraction │
|
||||
│ - API Key authentication │
|
||||
│ - Field-level permissions │
|
||||
│ │
|
||||
│ 🔍 Diff Preview System │
|
||||
│ - Before/after snapshots │
|
||||
│ - Changed fields detection │
|
||||
│ - HTML diff generation │
|
||||
│ │
|
||||
│ ✅ Approval Workflow │
|
||||
│ - PendingChange management │
|
||||
│ - Human approval required │
|
||||
│ - SignalR notifications │
|
||||
│ │
|
||||
│ 📊 Advanced Features │
|
||||
│ - Redis caching │
|
||||
│ - Audit logging │
|
||||
│ - Rate limiting │
|
||||
└──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Migration Phases (8 Weeks)
|
||||
|
||||
### Phase 1: Foundation (Week 1-2) - Story 13
|
||||
|
||||
**Goal**: Setup SDK infrastructure and validate compatibility
|
||||
|
||||
**Tasks**:
|
||||
1. Install `Microsoft.MCP` NuGet package
|
||||
2. Create PoC Tool/Resource using SDK
|
||||
3. Verify compatibility with existing architecture
|
||||
4. Performance baseline benchmarks
|
||||
5. Team training on SDK APIs
|
||||
|
||||
**Deliverables**:
|
||||
- SDK installed and configured
|
||||
- PoC validates SDK works with ColaFlow
|
||||
- Performance baseline report
|
||||
- Migration guide for developers
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] SDK integrated into ColaFlow.Modules.Mcp project
|
||||
- [ ] PoC Tool successfully called from Claude Desktop
|
||||
- [ ] Performance baseline recorded (response time, throughput)
|
||||
- [ ] Zero conflicts with existing Clean Architecture
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Tool Migration (Week 3-4) - Story 14
|
||||
|
||||
**Goal**: Migrate all 10 Tools to SDK attribute-based registration
|
||||
|
||||
**Tools to Migrate**:
|
||||
1. `create_issue` → `[McpTool]` attribute
|
||||
2. `update_status` → `[McpTool]` attribute
|
||||
3. `add_comment` → `[McpTool]` attribute
|
||||
4. `assign_issue` → `[McpTool]` attribute
|
||||
5. `create_sprint` → `[McpTool]` attribute
|
||||
6. `update_sprint` → `[McpTool]` attribute
|
||||
7. `log_decision` → `[McpTool]` attribute
|
||||
8. `generate_prd` → `[McpTool]` attribute
|
||||
9. `split_epic` → `[McpTool]` attribute
|
||||
10. `detect_risks` → `[McpTool]` attribute
|
||||
|
||||
**Migration Pattern**:
|
||||
```csharp
|
||||
// BEFORE (Custom)
|
||||
public class CreateIssueTool : IMcpTool
|
||||
{
|
||||
public string Name => "create_issue";
|
||||
public string Description => "Create a new issue";
|
||||
public McpToolInputSchema InputSchema => ...;
|
||||
|
||||
public async Task<McpToolResult> ExecuteAsync(...)
|
||||
{
|
||||
// Custom routing logic
|
||||
}
|
||||
}
|
||||
|
||||
// AFTER (SDK)
|
||||
[McpTool(
|
||||
Name = "create_issue",
|
||||
Description = "Create a new issue (Epic/Story/Task)"
|
||||
)]
|
||||
public class CreateIssueTool
|
||||
{
|
||||
[McpToolParameter(Required = true)]
|
||||
public Guid ProjectId { get; set; }
|
||||
|
||||
[McpToolParameter(Required = true)]
|
||||
public string Title { get; set; }
|
||||
|
||||
[McpToolParameter]
|
||||
public string? Description { get; set; }
|
||||
|
||||
public async Task<McpToolResult> ExecuteAsync(
|
||||
McpContext context,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// Business logic stays the same
|
||||
// DiffPreviewService integration preserved
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
- All 10 Tools migrated to SDK attributes
|
||||
- DiffPreviewService integration maintained
|
||||
- Integration tests updated
|
||||
- Performance comparison report
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] All Tools work with `[McpTool]` attribute
|
||||
- [ ] Diff Preview workflow preserved (no breaking changes)
|
||||
- [ ] Integration tests pass (>80% coverage)
|
||||
- [ ] Performance improvement measured (target: 20%+)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Resource Migration (Week 5) - Story 15
|
||||
|
||||
**Goal**: Migrate all 11 Resources to SDK attribute-based registration
|
||||
|
||||
**Resources to Migrate**:
|
||||
1. `projects.list` → `[McpResource]`
|
||||
2. `projects.get/{id}` → `[McpResource]`
|
||||
3. `issues.search` → `[McpResource]`
|
||||
4. `issues.get/{id}` → `[McpResource]`
|
||||
5. `sprints.current` → `[McpResource]`
|
||||
6. `sprints.list` → `[McpResource]`
|
||||
7. `users.list` → `[McpResource]`
|
||||
8. `docs.prd/{projectId}` → `[McpResource]`
|
||||
9. `reports.daily/{date}` → `[McpResource]`
|
||||
10. `reports.velocity` → `[McpResource]`
|
||||
11. `audit.history/{entityId}` → `[McpResource]`
|
||||
|
||||
**Migration Pattern**:
|
||||
```csharp
|
||||
// BEFORE (Custom)
|
||||
public class ProjectsListResource : IMcpResource
|
||||
{
|
||||
public string Uri => "colaflow://projects.list";
|
||||
public string Name => "Projects List";
|
||||
|
||||
public async Task<McpResourceContent> GetContentAsync(...)
|
||||
{
|
||||
// Custom logic
|
||||
}
|
||||
}
|
||||
|
||||
// AFTER (SDK)
|
||||
[McpResource(
|
||||
Uri = "colaflow://projects.list",
|
||||
Name = "Projects List",
|
||||
Description = "List all projects in current tenant",
|
||||
MimeType = "application/json"
|
||||
)]
|
||||
public class ProjectsListResource
|
||||
{
|
||||
private readonly IProjectRepository _repo;
|
||||
private readonly ITenantContext _tenant;
|
||||
private readonly IMemoryCache _cache; // Redis preserved
|
||||
|
||||
public async Task<McpResourceContent> GetContentAsync(
|
||||
McpContext context,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// Business logic stays the same
|
||||
// Multi-tenant filtering preserved
|
||||
// Redis caching preserved
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
- All 11 Resources migrated to SDK attributes
|
||||
- Multi-tenant isolation verified
|
||||
- Redis caching maintained
|
||||
- Performance tests passed
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] All Resources work with `[McpResource]` attribute
|
||||
- [ ] Multi-tenant isolation 100% verified
|
||||
- [ ] Redis cache hit rate > 80% maintained
|
||||
- [ ] Response time < 200ms (P95)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Transport Layer (Week 6) - Story 16
|
||||
|
||||
**Goal**: Replace custom HTTP middleware with SDK transport
|
||||
|
||||
**Current Custom Transport**:
|
||||
```csharp
|
||||
// Custom middleware (will be removed)
|
||||
app.UseMiddleware<McpProtocolMiddleware>();
|
||||
app.UseMiddleware<ApiKeyAuthMiddleware>();
|
||||
```
|
||||
|
||||
**SDK Transport Configuration**:
|
||||
```csharp
|
||||
// SDK-based transport
|
||||
builder.Services.AddMcpServer(options =>
|
||||
{
|
||||
// stdio transport (for CLI tools like Claude Desktop)
|
||||
options.UseStdioTransport();
|
||||
|
||||
// HTTP/SSE transport (for web-based clients)
|
||||
options.UseHttpTransport(http =>
|
||||
{
|
||||
http.BasePath = "/mcp";
|
||||
http.EnableSse = true; // Server-Sent Events
|
||||
});
|
||||
|
||||
// Custom authentication (preserve API Key auth)
|
||||
options.AddAuthentication<ApiKeyAuthHandler>();
|
||||
|
||||
// Custom authorization (preserve field-level permissions)
|
||||
options.AddAuthorization<FieldLevelAuthHandler>();
|
||||
});
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
- Custom middleware removed
|
||||
- SDK transport configured (stdio + HTTP/SSE)
|
||||
- API Key authentication migrated to SDK pipeline
|
||||
- Field-level permissions preserved
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] stdio transport works (Claude Desktop compatibility)
|
||||
- [ ] HTTP/SSE transport works (web client compatibility)
|
||||
- [ ] API Key authentication functional
|
||||
- [ ] Field-level permissions enforced
|
||||
- [ ] Zero breaking changes for existing clients
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Testing & Optimization (Week 7-8) - Story 17
|
||||
|
||||
**Goal**: Comprehensive testing, performance tuning, and documentation
|
||||
|
||||
#### Week 7: Integration Testing & Bug Fixes
|
||||
|
||||
**Tasks**:
|
||||
1. **End-to-End Testing**
|
||||
- Claude Desktop integration test (stdio)
|
||||
- Web client integration test (HTTP/SSE)
|
||||
- Multi-tenant isolation verification
|
||||
- Diff Preview workflow validation
|
||||
|
||||
2. **Performance Testing**
|
||||
- Benchmark Tools (target: 20%+ improvement)
|
||||
- Benchmark Resources (target: 30%+ improvement)
|
||||
- Concurrent request testing (100 req/s)
|
||||
- Memory usage profiling
|
||||
|
||||
3. **Security Audit**
|
||||
- API Key brute force test
|
||||
- Cross-tenant access attempts
|
||||
- Field-level permission bypass tests
|
||||
- SQL injection attempts
|
||||
|
||||
4. **Bug Fixes**
|
||||
- Fix integration test failures
|
||||
- Address performance bottlenecks
|
||||
- Fix security vulnerabilities (if found)
|
||||
|
||||
#### Week 8: Documentation & Production Readiness
|
||||
|
||||
**Tasks**:
|
||||
1. **Architecture Documentation**
|
||||
- Update `mcp-server-architecture.md` with SDK details
|
||||
- Create SDK migration guide for developers
|
||||
- Document hybrid architecture decisions
|
||||
- Add troubleshooting guide
|
||||
|
||||
2. **API Documentation**
|
||||
- Update OpenAPI/Swagger specs
|
||||
- Document Tool parameter schemas
|
||||
- Document Resource URI patterns
|
||||
- Add example requests/responses
|
||||
|
||||
3. **Code Cleanup**
|
||||
- Remove old custom protocol code
|
||||
- Delete obsolete interfaces (IMcpTool, IMcpResource)
|
||||
- Clean up unused NuGet packages
|
||||
- Update code comments
|
||||
|
||||
4. **Production Readiness**
|
||||
- Deploy to staging environment
|
||||
- Smoke testing with real AI clients
|
||||
- Performance validation
|
||||
- Final code review
|
||||
|
||||
**Deliverables**:
|
||||
- Comprehensive test suite (>80% coverage)
|
||||
- Performance report (vs. baseline)
|
||||
- Security audit report (zero CRITICAL issues)
|
||||
- Updated architecture documentation
|
||||
- Production deployment guide
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Integration tests pass (>80% coverage)
|
||||
- [ ] Performance improved by ≥20%
|
||||
- [ ] Security audit clean (0 CRITICAL, 0 HIGH)
|
||||
- [ ] Documentation complete and reviewed
|
||||
- [ ] Production-ready checklist signed off
|
||||
|
||||
---
|
||||
|
||||
## Stories Breakdown
|
||||
|
||||
This Epic is broken down into 5 child Stories:
|
||||
|
||||
- [ ] [Story 13](sprint_5_story_13.md) - MCP SDK Foundation & PoC (Week 1-2) - `not_started`
|
||||
- [ ] [Story 14](sprint_5_story_14.md) - Tool Migration to SDK (Week 3-4) - `not_started`
|
||||
- [ ] [Story 15](sprint_5_story_15.md) - Resource Migration to SDK (Week 5) - `not_started`
|
||||
- [ ] [Story 16](sprint_5_story_16.md) - Transport Layer Migration (Week 6) - `not_started`
|
||||
- [ ] [Story 17](sprint_5_story_17.md) - Testing & Optimization (Week 7-8) - `not_started`
|
||||
|
||||
**Progress**: 0/5 stories completed (0%)
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### High-Priority Risks
|
||||
|
||||
| Risk ID | Description | Impact | Probability | Mitigation |
|
||||
|---------|-------------|--------|-------------|------------|
|
||||
| RISK-001 | SDK breaking changes during migration | High | Low | Lock SDK version, gradual migration |
|
||||
| RISK-002 | Performance regression | High | Medium | Continuous benchmarking, rollback plan |
|
||||
| RISK-003 | DiffPreview integration conflicts | Medium | Medium | Thorough testing, preserve interfaces |
|
||||
| RISK-004 | Client compatibility issues | High | Low | Test with Claude Desktop early |
|
||||
| RISK-005 | Multi-tenant isolation bugs | Critical | Very Low | 100% test coverage, security audit |
|
||||
|
||||
### Mitigation Strategies
|
||||
|
||||
1. **Phased Migration**: 5 phases allow early detection of issues
|
||||
2. **Parallel Systems**: Keep old code until SDK fully validated
|
||||
3. **Feature Flags**: Enable/disable SDK via configuration
|
||||
4. **Rollback Plan**: Can revert to custom implementation if needed
|
||||
5. **Continuous Testing**: Run tests after each phase
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Prerequisites
|
||||
- ✅ Sprint 5 Phase 1-3 infrastructure (Stories 1-12)
|
||||
- ✅ Custom MCP implementation complete and working
|
||||
- ✅ DiffPreview service production-ready
|
||||
- ✅ Multi-tenant security verified
|
||||
|
||||
### External Dependencies
|
||||
- Microsoft .NET MCP SDK v1.0+ (NuGet)
|
||||
- Claude Desktop 1.0+ (for testing)
|
||||
- Continue VS Code Extension (for testing)
|
||||
|
||||
### Technical Requirements
|
||||
- .NET 9+ (already installed)
|
||||
- PostgreSQL 15+ (already configured)
|
||||
- Redis 7+ (already configured)
|
||||
|
||||
## Acceptance Criteria (Epic-Level)
|
||||
|
||||
### Functional Requirements
|
||||
- [ ] All 10 Tools migrated to SDK `[McpTool]` attributes
|
||||
- [ ] All 11 Resources migrated to SDK `[McpResource]` attributes
|
||||
- [ ] stdio transport works (Claude Desktop compatible)
|
||||
- [ ] HTTP/SSE transport works (web client compatible)
|
||||
- [ ] Diff Preview workflow preserved (no breaking changes)
|
||||
- [ ] Multi-tenant isolation 100% verified
|
||||
- [ ] API Key authentication functional
|
||||
- [ ] Field-level permissions enforced
|
||||
|
||||
### Performance Requirements
|
||||
- [ ] Response time improved by ≥20%
|
||||
- [ ] Tool execution time < 500ms (P95)
|
||||
- [ ] Resource query time < 200ms (P95)
|
||||
- [ ] Throughput ≥100 requests/second
|
||||
- [ ] Memory usage optimized (no leaks)
|
||||
|
||||
### Quality Requirements
|
||||
- [ ] Test coverage ≥80%
|
||||
- [ ] Zero CRITICAL security vulnerabilities
|
||||
- [ ] Zero HIGH security vulnerabilities
|
||||
- [ ] Code duplication <5%
|
||||
- [ ] All integration tests pass
|
||||
|
||||
### Documentation Requirements
|
||||
- [ ] Architecture documentation updated
|
||||
- [ ] API documentation complete
|
||||
- [ ] Migration guide published
|
||||
- [ ] Troubleshooting guide published
|
||||
- [ ] Code examples updated
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Code Quality
|
||||
- **Lines Removed**: 500-700 lines of custom protocol code
|
||||
- **Code Duplication**: <5%
|
||||
- **Test Coverage**: ≥80%
|
||||
- **Security Score**: 0 CRITICAL, 0 HIGH vulnerabilities
|
||||
|
||||
### Performance
|
||||
- **Response Time**: 20-40% improvement
|
||||
- **Throughput**: 100+ req/s (from 70 req/s)
|
||||
- **Memory Usage**: 10-20% reduction
|
||||
- **Cache Hit Rate**: >80% maintained
|
||||
|
||||
### Developer Experience
|
||||
- **Onboarding Time**: 50% faster (simpler SDK APIs)
|
||||
- **Code Readability**: +30% (attributes vs. manual registration)
|
||||
- **Maintenance Effort**: -60% (Microsoft maintains protocol)
|
||||
|
||||
## Related Documents
|
||||
|
||||
### Research & Design
|
||||
- [MCP SDK Integration Research](../research/mcp-sdk-integration-research.md)
|
||||
- [MCP Server Architecture](../architecture/mcp-server-architecture.md)
|
||||
- [Hybrid Architecture ADR](../architecture/adr/mcp-sdk-hybrid-approach.md)
|
||||
|
||||
### Sprint Planning
|
||||
- [Sprint 5 Plan](sprint_5.md)
|
||||
- [Product Roadmap](../../product.md) - M2 section
|
||||
|
||||
### Technical References
|
||||
- [Microsoft .NET MCP SDK](https://github.com/microsoft/mcp-dotnet)
|
||||
- [MCP Specification](https://spec.modelcontextprotocol.io/)
|
||||
- [ColaFlow MCP Module](../../colaflow-api/src/ColaFlow.Modules.Mcp/)
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
### Why Hybrid Architecture?
|
||||
|
||||
**Question**: Why not use 100% SDK?
|
||||
|
||||
**Answer**: ColaFlow has unique business requirements:
|
||||
1. **Diff Preview**: SDK doesn't provide preview mechanism (ColaFlow custom)
|
||||
2. **Approval Workflow**: SDK doesn't have human-in-the-loop (ColaFlow custom)
|
||||
3. **Multi-Tenant**: SDK doesn't enforce tenant isolation (ColaFlow custom)
|
||||
4. **Field Permissions**: SDK doesn't have field-level security (ColaFlow custom)
|
||||
|
||||
Hybrid approach gets **best of both worlds**:
|
||||
- SDK handles boring protocol stuff (60-70% code reduction)
|
||||
- ColaFlow handles business-critical stuff (security, approval)
|
||||
|
||||
### What Gets Deleted?
|
||||
|
||||
**Custom Code to Remove** (~700 lines):
|
||||
- `McpProtocolHandler.cs` (JSON-RPC parsing)
|
||||
- `McpProtocolMiddleware.cs` (HTTP middleware)
|
||||
- `IMcpTool.cs` interface (replaced by SDK attributes)
|
||||
- `IMcpResource.cs` interface (replaced by SDK attributes)
|
||||
- `McpRegistry.cs` (replaced by SDK discovery)
|
||||
- `McpRequest.cs` / `McpResponse.cs` DTOs (SDK provides)
|
||||
|
||||
**Custom Code to Keep** (~1200 lines):
|
||||
- `DiffPreviewService.cs` (business logic)
|
||||
- `PendingChangeService.cs` (approval workflow)
|
||||
- `ApiKeyAuthHandler.cs` (security)
|
||||
- `FieldLevelAuthHandler.cs` (permissions)
|
||||
- `TenantContextService.cs` (multi-tenant)
|
||||
|
||||
### Timeline Justification
|
||||
|
||||
**Why 8 weeks?**
|
||||
- **Week 1-2**: PoC + training (can't rush, need to understand SDK)
|
||||
- **Week 3-4**: 10 Tools migration (careful testing required)
|
||||
- **Week 5**: 11 Resources migration (simpler than Tools)
|
||||
- **Week 6**: Transport layer (critical, can't break clients)
|
||||
- **Week 7-8**: Testing + docs (quality gate, can't skip)
|
||||
|
||||
**Could it be faster?**
|
||||
- Yes, if we skip testing (NOT RECOMMENDED)
|
||||
- Yes, if we accept higher risk (NOT RECOMMENDED)
|
||||
- This is already aggressive timeline (1.6 weeks per phase)
|
||||
|
||||
### Post-Migration Benefits
|
||||
|
||||
**Developer Velocity**:
|
||||
- New Tool creation: 30 min (was 2 hours)
|
||||
- New Resource creation: 15 min (was 1 hour)
|
||||
- Onboarding new developers: 2 days (was 5 days)
|
||||
|
||||
**Maintenance Burden**:
|
||||
- Protocol updates: 0 hours (Microsoft handles)
|
||||
- Bug fixes: -60% effort (less custom code)
|
||||
- Feature additions: +40% faster (SDK simplifies)
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-11-09 by Product Manager Agent
|
||||
**Epic Owner**: Backend Team Lead
|
||||
**Estimated Start**: 2025-11-27 (After Sprint 5 Phase 1-3)
|
||||
**Estimated Completion**: 2026-01-22 (Week 8 of Sprint 5)
|
||||
**Status**: Not Started (planning complete)
|
||||
441
docs/plans/sprint_5_story_13.md
Normal file
441
docs/plans/sprint_5_story_13.md
Normal file
@@ -0,0 +1,441 @@
|
||||
---
|
||||
story_id: story_13
|
||||
sprint_id: sprint_5
|
||||
parent_story_id: story_0
|
||||
status: not_started
|
||||
priority: P0
|
||||
assignee: backend
|
||||
created_date: 2025-11-09
|
||||
estimated_days: 10
|
||||
phase: 1
|
||||
---
|
||||
|
||||
# Story 13: MCP SDK Foundation & Proof of Concept
|
||||
|
||||
**Parent Epic**: [Story 0](sprint_5_story_0.md) - Integrate Microsoft .NET MCP SDK
|
||||
**Phase**: 1 - Foundation (Week 1-2)
|
||||
**Priority**: P0 - Critical
|
||||
**Estimated Effort**: 10 days (2 weeks)
|
||||
|
||||
## User Story
|
||||
|
||||
**As** a backend developer,
|
||||
**I want** to install and validate the Microsoft .NET MCP SDK,
|
||||
**So that** we can confidently migrate from custom MCP implementation to the official SDK.
|
||||
|
||||
## Business Value
|
||||
|
||||
- **Risk Mitigation**: Validate SDK compatibility before committing to full migration
|
||||
- **Performance Baseline**: Establish performance metrics for comparison
|
||||
- **Team Readiness**: Train team on SDK APIs and patterns
|
||||
- **Decision Validation**: Confirm hybrid architecture approach is viable
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Microsoft .NET MCP SDK installed from NuGet
|
||||
- [ ] PoC Tool successfully registered using `[McpTool]` attribute
|
||||
- [ ] PoC Resource successfully registered using `[McpResource]` attribute
|
||||
- [ ] PoC validated with Claude Desktop (stdio transport)
|
||||
- [ ] Performance baseline recorded (response time, throughput, memory)
|
||||
- [ ] Compatibility verified with existing Clean Architecture
|
||||
- [ ] Team training completed (2-hour workshop)
|
||||
- [ ] Migration guide document created
|
||||
|
||||
## Technical Scope
|
||||
|
||||
### 1. SDK Installation & Configuration
|
||||
|
||||
**Goal**: Install SDK and configure basic infrastructure
|
||||
|
||||
**Tasks**:
|
||||
1. Add NuGet package reference
|
||||
2. Configure SDK services in DI container
|
||||
3. Setup basic transport (stdio only for PoC)
|
||||
4. Verify SDK initialization
|
||||
|
||||
**Expected Changes**:
|
||||
```csharp
|
||||
// ColaFlow.Modules.Mcp.csproj
|
||||
<PackageReference Include="Microsoft.MCP" Version="1.0.0" />
|
||||
<PackageReference Include="Microsoft.MCP.Server" Version="1.0.0" />
|
||||
```
|
||||
|
||||
```csharp
|
||||
// Program.cs or Startup.cs
|
||||
services.AddMcpServer(options =>
|
||||
{
|
||||
options.UseStdioTransport(); // PoC only
|
||||
options.DiscoverToolsAndResources(); // Auto-discovery
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. PoC Tool Implementation
|
||||
|
||||
**Goal**: Create one Tool using SDK to validate approach
|
||||
|
||||
**PoC Tool**: `ping` (simple echo tool for testing)
|
||||
|
||||
**Implementation**:
|
||||
```csharp
|
||||
// ColaFlow.Modules.Mcp/Tools/PingTool.cs
|
||||
using Microsoft.MCP;
|
||||
|
||||
[McpTool(
|
||||
Name = "ping",
|
||||
Description = "Test tool that echoes back the input message"
|
||||
)]
|
||||
public class PingTool
|
||||
{
|
||||
[McpToolParameter(
|
||||
Name = "message",
|
||||
Description = "Message to echo back",
|
||||
Required = true
|
||||
)]
|
||||
public string Message { get; set; } = string.Empty;
|
||||
|
||||
[McpToolParameter(
|
||||
Name = "delay_ms",
|
||||
Description = "Optional delay in milliseconds",
|
||||
Required = false
|
||||
)]
|
||||
public int? DelayMs { get; set; }
|
||||
|
||||
public async Task<McpToolResult> ExecuteAsync(
|
||||
McpContext context,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
if (DelayMs.HasValue)
|
||||
{
|
||||
await Task.Delay(DelayMs.Value, cancellationToken);
|
||||
}
|
||||
|
||||
return McpToolResult.Success(new
|
||||
{
|
||||
Echo = Message,
|
||||
Timestamp = DateTime.UtcNow,
|
||||
TenantId = context.TenantId, // Verify tenant context works
|
||||
UserId = context.UserId
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Steps**:
|
||||
1. Register tool (automatic via SDK discovery)
|
||||
2. Call tool from Claude Desktop
|
||||
3. Verify response correctness
|
||||
4. Measure performance
|
||||
|
||||
---
|
||||
|
||||
### 3. PoC Resource Implementation
|
||||
|
||||
**Goal**: Create one Resource using SDK to validate approach
|
||||
|
||||
**PoC Resource**: `system.info` (system metadata)
|
||||
|
||||
**Implementation**:
|
||||
```csharp
|
||||
// ColaFlow.Modules.Mcp/Resources/SystemInfoResource.cs
|
||||
using Microsoft.MCP;
|
||||
|
||||
[McpResource(
|
||||
Uri = "colaflow://system.info",
|
||||
Name = "System Information",
|
||||
Description = "Get ColaFlow system metadata and health status",
|
||||
MimeType = "application/json"
|
||||
)]
|
||||
public class SystemInfoResource
|
||||
{
|
||||
private readonly ITenantContext _tenantContext;
|
||||
private readonly IConfiguration _config;
|
||||
|
||||
public SystemInfoResource(
|
||||
ITenantContext tenantContext,
|
||||
IConfiguration config)
|
||||
{
|
||||
_tenantContext = tenantContext;
|
||||
_config = config;
|
||||
}
|
||||
|
||||
public async Task<McpResourceContent> GetContentAsync(
|
||||
McpContext context,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var info = new
|
||||
{
|
||||
Version = "1.0.0",
|
||||
Environment = _config["Environment"],
|
||||
TenantId = _tenantContext.CurrentTenantId,
|
||||
ServerTime = DateTime.UtcNow,
|
||||
Uptime = GetUptime()
|
||||
};
|
||||
|
||||
return McpResourceContent.Json(info);
|
||||
}
|
||||
|
||||
private TimeSpan GetUptime()
|
||||
{
|
||||
return DateTime.UtcNow - Process.GetCurrentProcess().StartTime;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Steps**:
|
||||
1. Register resource (automatic via SDK discovery)
|
||||
2. Query resource from Claude Desktop
|
||||
3. Verify JSON response format
|
||||
4. Verify tenant context isolation
|
||||
|
||||
---
|
||||
|
||||
### 4. Claude Desktop Integration Testing
|
||||
|
||||
**Goal**: Validate SDK works with real MCP client
|
||||
|
||||
**Setup**:
|
||||
1. Configure Claude Desktop MCP client
|
||||
2. Add ColaFlow as MCP server in config
|
||||
3. Test Tool and Resource calls
|
||||
4. Verify error handling
|
||||
|
||||
**Claude Desktop Config** (`claude_desktop_config.json`):
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"colaflow-poc": {
|
||||
"command": "dotnet",
|
||||
"args": ["run", "--project", "ColaFlow.Modules.Mcp"],
|
||||
"env": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Test Cases**:
|
||||
1. **Tool Call**: `ping` with message "Hello MCP SDK"
|
||||
2. **Resource Query**: `colaflow://system.info`
|
||||
3. **Error Handling**: Invalid tool parameters
|
||||
4. **Multi-Tenant**: Verify tenant isolation
|
||||
|
||||
---
|
||||
|
||||
### 5. Performance Baseline Benchmarking
|
||||
|
||||
**Goal**: Establish baseline metrics for comparison
|
||||
|
||||
**Metrics to Measure**:
|
||||
1. **Tool Execution Time** (P50, P95, P99)
|
||||
2. **Resource Query Time** (P50, P95, P99)
|
||||
3. **Memory Usage** (baseline, peak)
|
||||
4. **Throughput** (requests/second)
|
||||
5. **SDK Overhead** (protocol parsing time)
|
||||
|
||||
**Benchmark Tool**: BenchmarkDotNet
|
||||
|
||||
**Benchmark Implementation**:
|
||||
```csharp
|
||||
[MemoryDiagnoser]
|
||||
[MinColumn, MaxColumn, MeanColumn, MedianColumn]
|
||||
public class McpSdkBenchmarks
|
||||
{
|
||||
private PingTool _tool = null!;
|
||||
private SystemInfoResource _resource = null!;
|
||||
|
||||
[GlobalSetup]
|
||||
public void Setup()
|
||||
{
|
||||
_tool = new PingTool();
|
||||
_resource = new SystemInfoResource(...);
|
||||
}
|
||||
|
||||
[Benchmark]
|
||||
public async Task<McpToolResult> ExecutePingTool()
|
||||
{
|
||||
return await _tool.ExecuteAsync(
|
||||
new McpContext { TenantId = Guid.NewGuid() },
|
||||
CancellationToken.None);
|
||||
}
|
||||
|
||||
[Benchmark]
|
||||
public async Task<McpResourceContent> QuerySystemInfo()
|
||||
{
|
||||
return await _resource.GetContentAsync(
|
||||
new McpContext { TenantId = Guid.NewGuid() },
|
||||
CancellationToken.None);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Baseline** (custom implementation):
|
||||
- Tool execution: 150-200ms (P95)
|
||||
- Resource query: 80-120ms (P95)
|
||||
- Throughput: 70 req/s
|
||||
- Memory: 150-200 MB baseline
|
||||
|
||||
---
|
||||
|
||||
### 6. Compatibility Verification
|
||||
|
||||
**Goal**: Ensure SDK doesn't break existing architecture
|
||||
|
||||
**Checks**:
|
||||
1. **DI Container**: SDK services register without conflicts
|
||||
2. **Clean Architecture**: SDK fits into Infrastructure layer
|
||||
3. **CQRS Pattern**: SDK doesn't interfere with MediatR
|
||||
4. **Multi-Tenant**: TenantContext injection works
|
||||
5. **Authentication**: API Key middleware compatible
|
||||
|
||||
**Compatibility Matrix**:
|
||||
|
||||
| Component | SDK Compatible? | Notes |
|
||||
|-----------|----------------|-------|
|
||||
| ASP.NET Core DI | ✅ Yes | SDK uses standard DI |
|
||||
| MediatR CQRS | ✅ Yes | No conflicts |
|
||||
| EF Core | ✅ Yes | No database layer changes |
|
||||
| SignalR | ✅ Yes | Independent layers |
|
||||
| TenantContext | ⚠️ Verify | Need custom integration |
|
||||
| API Key Auth | ⚠️ Verify | Need custom middleware |
|
||||
| Redis Cache | ✅ Yes | No conflicts |
|
||||
|
||||
---
|
||||
|
||||
### 7. Team Training
|
||||
|
||||
**Goal**: Educate team on SDK usage
|
||||
|
||||
**Training Workshop** (2 hours):
|
||||
1. **SDK Overview** (30 min)
|
||||
- Architecture
|
||||
- Attribute system
|
||||
- Tool/Resource lifecycle
|
||||
|
||||
2. **Hands-On Coding** (60 min)
|
||||
- Create a simple Tool
|
||||
- Create a simple Resource
|
||||
- Test with Claude Desktop
|
||||
|
||||
3. **Q&A and Discussion** (30 min)
|
||||
- Migration concerns
|
||||
- Hybrid architecture strategy
|
||||
- Timeline and responsibilities
|
||||
|
||||
**Training Materials**:
|
||||
- Slide deck (20 slides)
|
||||
- Code examples repository
|
||||
- Migration guide document
|
||||
- FAQ document
|
||||
|
||||
---
|
||||
|
||||
## Tasks Breakdown
|
||||
|
||||
- [ ] [Task 1](sprint_5_story_13_task_1.md) - Install SDK and configure infrastructure - 1 day
|
||||
- [ ] [Task 2](sprint_5_story_13_task_2.md) - Implement PoC Tool (ping) - 1 day
|
||||
- [ ] [Task 3](sprint_5_story_13_task_3.md) - Implement PoC Resource (system.info) - 1 day
|
||||
- [ ] [Task 4](sprint_5_story_13_task_4.md) - Claude Desktop integration testing - 2 days
|
||||
- [ ] [Task 5](sprint_5_story_13_task_5.md) - Performance baseline benchmarking - 2 days
|
||||
- [ ] [Task 6](sprint_5_story_13_task_6.md) - Compatibility verification testing - 1 day
|
||||
- [ ] [Task 7](sprint_5_story_13_task_7.md) - Team training and documentation - 2 days
|
||||
|
||||
**Progress**: 0/7 tasks completed (0%)
|
||||
|
||||
## Deliverables
|
||||
|
||||
1. **Code**:
|
||||
- SDK NuGet packages installed
|
||||
- `PingTool.cs` (PoC Tool)
|
||||
- `SystemInfoResource.cs` (PoC Resource)
|
||||
- Benchmark suite
|
||||
|
||||
2. **Documentation**:
|
||||
- SDK Integration Guide (10 pages)
|
||||
- Performance Baseline Report (5 pages)
|
||||
- Compatibility Matrix (1 page)
|
||||
- Training slide deck (20 slides)
|
||||
|
||||
3. **Test Results**:
|
||||
- Claude Desktop integration test report
|
||||
- Benchmark results (charts and tables)
|
||||
- Compatibility verification report
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- PoC Tool parameter validation
|
||||
- PoC Resource JSON serialization
|
||||
- Error handling edge cases
|
||||
|
||||
### Integration Tests
|
||||
- Claude Desktop Tool call (stdio transport)
|
||||
- Claude Desktop Resource query
|
||||
- Error response handling
|
||||
|
||||
### Performance Tests
|
||||
- BenchmarkDotNet suite
|
||||
- Memory profiling
|
||||
- Throughput testing (100 concurrent requests)
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
| Risk ID | Description | Mitigation |
|
||||
|---------|-------------|------------|
|
||||
| RISK-013-1 | SDK incompatible with Clean Architecture | Early PoC will reveal issues, can adjust approach |
|
||||
| RISK-013-2 | Performance worse than custom implementation | Benchmark early, can optimize or abort migration |
|
||||
| RISK-013-3 | TenantContext integration doesn't work | Custom middleware can bridge the gap |
|
||||
| RISK-013-4 | Claude Desktop connection fails | Test with multiple clients (Continue, Cline) |
|
||||
| RISK-013-5 | Team learning curve too steep | Provide comprehensive training and pair programming |
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Technical Success
|
||||
- [ ] PoC Tool and Resource work end-to-end
|
||||
- [ ] Performance baseline recorded
|
||||
- [ ] Zero compatibility conflicts found
|
||||
- [ ] Claude Desktop integration successful
|
||||
|
||||
### Team Success
|
||||
- [ ] All team members complete training
|
||||
- [ ] Team confident in SDK approach (survey: >80% confidence)
|
||||
- [ ] Migration guide reviewed and approved
|
||||
|
||||
### Decision Gate
|
||||
**GO/NO-GO Decision**: After this story completes, team decides:
|
||||
- ✅ **GO**: Proceed with full migration (Stories 14-17)
|
||||
- ❌ **NO-GO**: Abort migration, keep custom implementation
|
||||
|
||||
**Decision Criteria**:
|
||||
- Performance acceptable (>=baseline or <10% regression)
|
||||
- Compatibility verified (zero blocking issues)
|
||||
- Team confident (>80% in survey)
|
||||
- No CRITICAL risks identified
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] SDK installed and configured
|
||||
- [ ] PoC Tool works (tested with Claude Desktop)
|
||||
- [ ] PoC Resource works (tested with Claude Desktop)
|
||||
- [ ] Performance baseline documented
|
||||
- [ ] Compatibility matrix complete (all green or yellow)
|
||||
- [ ] Team training conducted (100% attendance)
|
||||
- [ ] Migration guide reviewed and approved
|
||||
- [ ] Code reviewed by architect
|
||||
- [ ] GO/NO-GO decision made and documented
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Epic Story 0](sprint_5_story_0.md) - MCP SDK Migration Epic
|
||||
- [Research Report](../research/mcp-sdk-integration-research.md)
|
||||
- [Sprint 5 Plan](sprint_5.md)
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-11-09 by Product Manager Agent
|
||||
**Owner**: Backend Team Lead
|
||||
**Start Date**: 2025-11-27 (Week 1 of Sprint 5 Extension)
|
||||
**Target Date**: 2025-12-06 (End of Week 2)
|
||||
**Status**: Not Started
|
||||
221
docs/plans/sprint_5_story_14.md
Normal file
221
docs/plans/sprint_5_story_14.md
Normal file
@@ -0,0 +1,221 @@
|
||||
---
|
||||
story_id: story_14
|
||||
sprint_id: sprint_5
|
||||
parent_story_id: story_0
|
||||
status: not_started
|
||||
priority: P0
|
||||
assignee: backend
|
||||
created_date: 2025-11-09
|
||||
estimated_days: 10
|
||||
phase: 2
|
||||
---
|
||||
|
||||
# Story 14: Tool Migration to SDK Attributes
|
||||
|
||||
**Parent Epic**: [Story 0](sprint_5_story_0.md) - Integrate Microsoft .NET MCP SDK
|
||||
**Phase**: 2 - Tool Migration (Week 3-4)
|
||||
**Priority**: P0 - Critical
|
||||
**Estimated Effort**: 10 days (2 weeks)
|
||||
**Dependencies**: Story 13 (Foundation must be complete)
|
||||
|
||||
## User Story
|
||||
|
||||
**As** a backend developer,
|
||||
**I want** to migrate all 10 MCP Tools from custom implementation to SDK attribute-based registration,
|
||||
**So that** we reduce boilerplate code and improve maintainability while preserving DiffPreview integration.
|
||||
|
||||
## Business Value
|
||||
|
||||
- **Code Reduction**: Remove 300-400 lines of custom Tool infrastructure
|
||||
- **Developer Experience**: Attribute-based registration is cleaner and more intuitive
|
||||
- **Performance**: SDK optimizations improve Tool execution by 20-30%
|
||||
- **Maintainability**: Microsoft maintains protocol layer, we focus on business logic
|
||||
|
||||
## Tools to Migrate (10 Total)
|
||||
|
||||
### High Priority Tools (P0)
|
||||
1. `create_issue` - Create Epic/Story/Task
|
||||
2. `update_status` - Change issue status
|
||||
3. `add_comment` - Add comment to issue
|
||||
4. `assign_issue` - Assign issue to user
|
||||
|
||||
### Medium Priority Tools (P1)
|
||||
5. `create_sprint` - Create new Sprint
|
||||
6. `update_sprint` - Update Sprint details
|
||||
7. `log_decision` - Log architecture decision
|
||||
|
||||
### Low Priority Tools (P2)
|
||||
8. `generate_prd` - AI-generate PRD from description
|
||||
9. `split_epic` - Split Epic into Stories
|
||||
10. `detect_risks` - Detect project risks
|
||||
|
||||
## Migration Pattern
|
||||
|
||||
### Before (Custom Implementation)
|
||||
```csharp
|
||||
public class CreateIssueTool : IMcpTool
|
||||
{
|
||||
public string Name => "create_issue";
|
||||
public string Description => "Create a new issue";
|
||||
public McpToolInputSchema InputSchema => new()
|
||||
{
|
||||
Type = "object",
|
||||
Properties = new Dictionary<string, object>
|
||||
{
|
||||
["projectId"] = new { type = "string", format = "uuid" },
|
||||
["title"] = new { type = "string", minLength = 1 }
|
||||
},
|
||||
Required = new[] { "projectId", "title" }
|
||||
};
|
||||
|
||||
public async Task<McpToolResult> ExecuteAsync(
|
||||
McpToolCall toolCall,
|
||||
CancellationToken ct)
|
||||
{
|
||||
// Manual parameter extraction
|
||||
var projectId = GetParam<Guid>(toolCall.Arguments, "projectId");
|
||||
var title = GetParam<string>(toolCall.Arguments, "title");
|
||||
|
||||
// Business logic...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### After (SDK Attributes)
|
||||
```csharp
|
||||
[McpTool(
|
||||
Name = "create_issue",
|
||||
Description = "Create a new issue (Epic/Story/Task) with Diff Preview"
|
||||
)]
|
||||
public class CreateIssueTool
|
||||
{
|
||||
private readonly IDiffPreviewService _diffPreview;
|
||||
private readonly IPendingChangeService _pendingChange;
|
||||
|
||||
public CreateIssueTool(
|
||||
IDiffPreviewService diffPreview,
|
||||
IPendingChangeService pendingChange)
|
||||
{
|
||||
_diffPreview = diffPreview;
|
||||
_pendingChange = pendingChange;
|
||||
}
|
||||
|
||||
[McpToolParameter(Required = true)]
|
||||
public Guid ProjectId { get; set; }
|
||||
|
||||
[McpToolParameter(Required = true, MinLength = 1, MaxLength = 200)]
|
||||
public string Title { get; set; } = string.Empty;
|
||||
|
||||
[McpToolParameter]
|
||||
public string? Description { get; set; }
|
||||
|
||||
[McpToolParameter]
|
||||
public string Priority { get; set; } = "Medium";
|
||||
|
||||
public async Task<McpToolResult> ExecuteAsync(
|
||||
McpContext context,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// Parameters auto-bound by SDK
|
||||
|
||||
// Generate Diff Preview (preserve existing logic)
|
||||
var diff = await _diffPreview.GeneratePreviewAsync(
|
||||
null, // CREATE operation
|
||||
new { ProjectId, Title, Description, Priority },
|
||||
"CREATE",
|
||||
cancellationToken);
|
||||
|
||||
// Create PendingChange (preserve existing workflow)
|
||||
var pendingChange = await _pendingChange.CreateAsync(
|
||||
"create_issue",
|
||||
diff,
|
||||
cancellationToken);
|
||||
|
||||
return McpToolResult.Success(new
|
||||
{
|
||||
PendingChangeId = pendingChange.Id,
|
||||
Message = "Issue creation pending approval",
|
||||
DiffPreview = diff
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Changes
|
||||
|
||||
### What Changes
|
||||
- ✅ Tool registration (custom → SDK attributes)
|
||||
- ✅ Parameter declaration (schema → properties)
|
||||
- ✅ Parameter validation (manual → SDK automatic)
|
||||
- ✅ Error handling (custom → SDK standard)
|
||||
|
||||
### What Stays the Same
|
||||
- ✅ DiffPreviewService integration (preserved)
|
||||
- ✅ PendingChangeService workflow (preserved)
|
||||
- ✅ TenantContext access (preserved via McpContext)
|
||||
- ✅ API Key authentication (preserved)
|
||||
- ✅ Business logic (unchanged)
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] All 10 Tools migrated to `[McpTool]` attributes
|
||||
- [ ] DiffPreview workflow works for all write operations
|
||||
- [ ] PendingChange creation works correctly
|
||||
- [ ] Tool parameter validation automatic (SDK-based)
|
||||
- [ ] Integration tests pass (>80% coverage)
|
||||
- [ ] Performance improved by ≥20% (measured)
|
||||
- [ ] Claude Desktop can call all migrated Tools
|
||||
- [ ] Zero breaking changes for MCP clients
|
||||
|
||||
## Tasks Breakdown
|
||||
|
||||
- [ ] [Task 1](sprint_5_story_14_task_1.md) - Migrate P0 Tools (create_issue, update_status, add_comment, assign_issue) - 3 days
|
||||
- [ ] [Task 2](sprint_5_story_14_task_2.md) - Migrate P1 Tools (create_sprint, update_sprint, log_decision) - 2 days
|
||||
- [ ] [Task 3](sprint_5_story_14_task_3.md) - Migrate P2 Tools (generate_prd, split_epic, detect_risks) - 2 days
|
||||
- [ ] [Task 4](sprint_5_story_14_task_4.md) - Update integration tests for all Tools - 2 days
|
||||
- [ ] [Task 5](sprint_5_story_14_task_5.md) - Performance testing and optimization - 1 day
|
||||
|
||||
**Progress**: 0/5 tasks completed (0%)
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests (Per Tool)
|
||||
- Parameter validation (required, types, ranges)
|
||||
- DiffPreview generation correctness
|
||||
- PendingChange creation
|
||||
- Error handling (invalid params, missing tenant)
|
||||
|
||||
### Integration Tests (End-to-End)
|
||||
- Claude Desktop Tool calls
|
||||
- Diff Preview workflow
|
||||
- Approval/rejection flow
|
||||
- Multi-tenant isolation
|
||||
|
||||
### Performance Tests
|
||||
- Benchmark each Tool (before/after)
|
||||
- Target: 20-30% improvement
|
||||
- Memory profiling
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- **Code Reduction**: -300 lines (Tool infrastructure)
|
||||
- **Performance**: +20-30% faster Tool execution
|
||||
- **Test Coverage**: Maintain 80%+
|
||||
- **Developer Time**: 50% faster to add new Tools
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All 10 Tools migrated to SDK attributes
|
||||
- [ ] DiffPreview integration verified (all Tools)
|
||||
- [ ] Integration tests pass (>80% coverage)
|
||||
- [ ] Performance benchmarks show ≥20% improvement
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] Documentation updated
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-11-09 by Product Manager Agent
|
||||
**Owner**: Backend Team
|
||||
**Start Date**: 2025-12-09 (Week 3)
|
||||
**Target Date**: 2025-12-20 (End of Week 4)
|
||||
**Status**: Not Started
|
||||
212
docs/plans/sprint_5_story_15.md
Normal file
212
docs/plans/sprint_5_story_15.md
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
story_id: story_15
|
||||
sprint_id: sprint_5
|
||||
parent_story_id: story_0
|
||||
status: not_started
|
||||
priority: P0
|
||||
assignee: backend
|
||||
created_date: 2025-11-09
|
||||
estimated_days: 5
|
||||
phase: 3
|
||||
---
|
||||
|
||||
# Story 15: Resource Migration to SDK Attributes
|
||||
|
||||
**Parent Epic**: [Story 0](sprint_5_story_0.md) - Integrate Microsoft .NET MCP SDK
|
||||
**Phase**: 3 - Resource Migration (Week 5)
|
||||
**Priority**: P0 - Critical
|
||||
**Estimated Effort**: 5 days (1 week)
|
||||
**Dependencies**: Story 14 (Tool migration complete)
|
||||
|
||||
## User Story
|
||||
|
||||
**As** a backend developer,
|
||||
**I want** to migrate all 11 MCP Resources from custom implementation to SDK attribute-based registration,
|
||||
**So that** we reduce boilerplate code while preserving multi-tenant isolation and Redis caching.
|
||||
|
||||
## Business Value
|
||||
|
||||
- **Code Reduction**: Remove 200-250 lines of custom Resource infrastructure
|
||||
- **Performance**: SDK optimizations improve query speed by 30-40%
|
||||
- **Caching**: Preserve Redis caching with minimal changes
|
||||
- **Multi-Tenant**: Maintain 100% tenant isolation
|
||||
|
||||
## Resources to Migrate (11 Total)
|
||||
|
||||
### Core Resources (P0)
|
||||
1. `projects.list` - List all projects
|
||||
2. `projects.get/{id}` - Get project details
|
||||
3. `issues.search` - Search issues with filters
|
||||
4. `issues.get/{id}` - Get issue details
|
||||
5. `sprints.current` - Get active Sprint
|
||||
|
||||
### Supporting Resources (P1)
|
||||
6. `sprints.list` - List all Sprints
|
||||
7. `users.list` - List team members
|
||||
8. `docs.prd/{projectId}` - Get PRD document
|
||||
|
||||
### Advanced Resources (P2)
|
||||
9. `reports.daily/{date}` - Daily status report
|
||||
10. `reports.velocity` - Sprint velocity report
|
||||
11. `audit.history/{entityId}` - Audit log history
|
||||
|
||||
## Migration Pattern
|
||||
|
||||
### Before (Custom Implementation)
|
||||
```csharp
|
||||
public class ProjectsListResource : IMcpResource
|
||||
{
|
||||
public string Uri => "colaflow://projects.list";
|
||||
public string Name => "Projects List";
|
||||
public string Description => "List all projects";
|
||||
public string MimeType => "application/json";
|
||||
|
||||
private readonly IProjectRepository _repo;
|
||||
private readonly ITenantContext _tenant;
|
||||
|
||||
public async Task<McpResourceContent> GetContentAsync(
|
||||
McpResourceRequest request,
|
||||
CancellationToken ct)
|
||||
{
|
||||
var projects = await _repo.GetAllAsync(_tenant.CurrentTenantId);
|
||||
return new McpResourceContent
|
||||
{
|
||||
Uri = Uri,
|
||||
MimeType = MimeType,
|
||||
Text = JsonSerializer.Serialize(new { projects })
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### After (SDK Attributes)
|
||||
```csharp
|
||||
[McpResource(
|
||||
Uri = "colaflow://projects.list",
|
||||
Name = "Projects List",
|
||||
Description = "List all projects in current tenant",
|
||||
MimeType = "application/json"
|
||||
)]
|
||||
public class ProjectsListResource
|
||||
{
|
||||
private readonly IProjectRepository _repo;
|
||||
private readonly ITenantContext _tenant;
|
||||
private readonly IDistributedCache _cache; // Redis preserved
|
||||
|
||||
public ProjectsListResource(
|
||||
IProjectRepository repo,
|
||||
ITenantContext tenant,
|
||||
IDistributedCache cache)
|
||||
{
|
||||
_repo = repo;
|
||||
_tenant = tenant;
|
||||
_cache = cache;
|
||||
}
|
||||
|
||||
public async Task<McpResourceContent> GetContentAsync(
|
||||
McpContext context,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// Preserve Redis caching
|
||||
var cacheKey = $"mcp:projects:list:{_tenant.CurrentTenantId}";
|
||||
var cached = await _cache.GetStringAsync(cacheKey, cancellationToken);
|
||||
|
||||
if (cached != null)
|
||||
{
|
||||
return McpResourceContent.Json(cached);
|
||||
}
|
||||
|
||||
// Preserve multi-tenant filtering
|
||||
var projects = await _repo.GetAllAsync(
|
||||
_tenant.CurrentTenantId,
|
||||
cancellationToken);
|
||||
|
||||
var json = JsonSerializer.Serialize(new { projects });
|
||||
|
||||
// Cache for 5 minutes
|
||||
await _cache.SetStringAsync(
|
||||
cacheKey,
|
||||
json,
|
||||
new DistributedCacheEntryOptions
|
||||
{
|
||||
AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5)
|
||||
},
|
||||
cancellationToken);
|
||||
|
||||
return McpResourceContent.Json(json);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Changes
|
||||
|
||||
### What Changes
|
||||
- ✅ Resource registration (custom → SDK attributes)
|
||||
- ✅ URI declaration (property → attribute)
|
||||
- ✅ Metadata (Name, Description in attribute)
|
||||
|
||||
### What Stays the Same
|
||||
- ✅ TenantContext filtering (preserved)
|
||||
- ✅ Redis caching logic (preserved)
|
||||
- ✅ Query logic (unchanged)
|
||||
- ✅ Response format (unchanged)
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] All 11 Resources migrated to `[McpResource]` attributes
|
||||
- [ ] Multi-tenant isolation 100% verified
|
||||
- [ ] Redis cache hit rate >80% maintained
|
||||
- [ ] Response time <200ms (P95)
|
||||
- [ ] Integration tests pass
|
||||
- [ ] Claude Desktop can query all Resources
|
||||
- [ ] Zero breaking changes for MCP clients
|
||||
|
||||
## Tasks Breakdown
|
||||
|
||||
- [ ] [Task 1](sprint_5_story_15_task_1.md) - Migrate P0 Resources (projects, issues, sprints.current) - 2 days
|
||||
- [ ] [Task 2](sprint_5_story_15_task_2.md) - Migrate P1 Resources (sprints.list, users, docs) - 1 day
|
||||
- [ ] [Task 3](sprint_5_story_15_task_3.md) - Migrate P2 Resources (reports, audit) - 1 day
|
||||
- [ ] [Task 4](sprint_5_story_15_task_4.md) - Multi-tenant isolation testing and cache verification - 1 day
|
||||
|
||||
**Progress**: 0/4 tasks completed (0%)
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Multi-Tenant Isolation Tests
|
||||
- Verify TenantContext extraction from McpContext
|
||||
- Test cross-tenant access attempts (should return 404)
|
||||
- Validate Global Query Filters applied
|
||||
|
||||
### Cache Performance Tests
|
||||
- Measure cache hit rate (target: >80%)
|
||||
- Verify cache invalidation on data changes
|
||||
- Test TTL expiration
|
||||
|
||||
### Integration Tests
|
||||
- Claude Desktop resource queries
|
||||
- Query parameter handling
|
||||
- Error responses (404, 403, 500)
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- **Code Reduction**: -200 lines (Resource infrastructure)
|
||||
- **Performance**: +30-40% faster queries
|
||||
- **Cache Hit Rate**: Maintain >80%
|
||||
- **Multi-Tenant**: 100% isolation verified
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All 11 Resources migrated to SDK attributes
|
||||
- [ ] Multi-tenant isolation 100% verified
|
||||
- [ ] Redis caching verified (>80% hit rate)
|
||||
- [ ] Performance benchmarks show ≥30% improvement
|
||||
- [ ] Integration tests pass
|
||||
- [ ] Code reviewed and approved
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-11-09 by Product Manager Agent
|
||||
**Owner**: Backend Team
|
||||
**Start Date**: 2025-12-23 (Week 5)
|
||||
**Target Date**: 2025-12-27 (End of Week 5)
|
||||
**Status**: Not Started
|
||||
301
docs/plans/sprint_5_story_16.md
Normal file
301
docs/plans/sprint_5_story_16.md
Normal file
@@ -0,0 +1,301 @@
|
||||
---
|
||||
story_id: story_16
|
||||
sprint_id: sprint_5
|
||||
parent_story_id: story_0
|
||||
status: not_started
|
||||
priority: P0
|
||||
assignee: backend
|
||||
created_date: 2025-11-09
|
||||
estimated_days: 5
|
||||
phase: 4
|
||||
---
|
||||
|
||||
# Story 16: Transport Layer Migration to SDK
|
||||
|
||||
**Parent Epic**: [Story 0](sprint_5_story_0.md) - Integrate Microsoft .NET MCP SDK
|
||||
**Phase**: 4 - Transport Layer (Week 6)
|
||||
**Priority**: P0 - Critical
|
||||
**Estimated Effort**: 5 days (1 week)
|
||||
**Dependencies**: Story 15 (Resource migration complete)
|
||||
|
||||
## User Story
|
||||
|
||||
**As** a backend developer,
|
||||
**I want** to replace custom HTTP middleware with SDK transport layer,
|
||||
**So that** we support both stdio (CLI) and HTTP/SSE (web) transports with minimal code.
|
||||
|
||||
## Business Value
|
||||
|
||||
- **Multi-Transport**: Support stdio (Claude Desktop) + HTTP/SSE (web clients)
|
||||
- **Code Reduction**: Remove 150-200 lines of custom middleware
|
||||
- **Standard Compliance**: SDK handles MCP transport specification
|
||||
- **Future-Proof**: Easy to add WebSocket in future
|
||||
|
||||
## Current vs. Target Architecture
|
||||
|
||||
### Current (Custom Middleware)
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ Custom HTTP Middleware │
|
||||
├─────────────────────────────┤
|
||||
│ McpProtocolMiddleware │
|
||||
│ - JSON-RPC parsing │
|
||||
│ - Request routing │
|
||||
│ - Error handling │
|
||||
│ │
|
||||
│ ApiKeyAuthMiddleware │
|
||||
│ - API Key extraction │
|
||||
│ - Validation │
|
||||
│ - TenantContext setup │
|
||||
└─────────────────────────────┘
|
||||
↓
|
||||
MCP Handlers
|
||||
```
|
||||
|
||||
### Target (SDK Transport)
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ SDK Transport Layer │
|
||||
├─────────────────────────────┤
|
||||
│ stdio Transport │
|
||||
│ - Standard In/Out │
|
||||
│ - For CLI tools │
|
||||
│ │
|
||||
│ HTTP/SSE Transport │
|
||||
│ - REST API │
|
||||
│ - Server-Sent Events │
|
||||
│ - For web clients │
|
||||
└─────────────────────────────┘
|
||||
↓
|
||||
SDK Protocol Handler
|
||||
↓
|
||||
Custom Auth/Authz
|
||||
↓
|
||||
MCP Handlers
|
||||
```
|
||||
|
||||
## Transport Configuration
|
||||
|
||||
### stdio Transport (Claude Desktop)
|
||||
```csharp
|
||||
services.AddMcpServer(options =>
|
||||
{
|
||||
// stdio transport for CLI tools
|
||||
options.UseStdioTransport();
|
||||
});
|
||||
```
|
||||
|
||||
**Use Cases**:
|
||||
- Claude Desktop
|
||||
- VS Code Continue extension
|
||||
- CLI tools (Cline, etc.)
|
||||
|
||||
**Characteristics**:
|
||||
- Single-user mode
|
||||
- Process lifetime tied to parent process
|
||||
- No HTTP overhead
|
||||
- Fast and simple
|
||||
|
||||
---
|
||||
|
||||
### HTTP/SSE Transport (Web Clients)
|
||||
```csharp
|
||||
services.AddMcpServer(options =>
|
||||
{
|
||||
// HTTP/SSE transport for web clients
|
||||
options.UseHttpTransport(http =>
|
||||
{
|
||||
http.BasePath = "/mcp"; // Base URL
|
||||
http.EnableSse = true; // Server-Sent Events for notifications
|
||||
http.EnableCors = true; // CORS for web clients
|
||||
});
|
||||
});
|
||||
|
||||
// Map MCP endpoints
|
||||
app.MapMcpEndpoints("/mcp");
|
||||
```
|
||||
|
||||
**Endpoints**:
|
||||
- `POST /mcp/initialize` - Handshake
|
||||
- `POST /mcp/tools/list` - List Tools
|
||||
- `POST /mcp/tools/call` - Execute Tool
|
||||
- `POST /mcp/resources/list` - List Resources
|
||||
- `GET /mcp/resources/read` - Query Resource
|
||||
- `GET /mcp/sse` - SSE stream for notifications
|
||||
|
||||
**Use Cases**:
|
||||
- Web-based MCP clients
|
||||
- Custom integrations
|
||||
- Future ChatGPT plugin
|
||||
|
||||
**Characteristics**:
|
||||
- Multi-user mode
|
||||
- Stateless (requires API Key)
|
||||
- Supports SSE for real-time updates
|
||||
- CORS-enabled
|
||||
|
||||
---
|
||||
|
||||
## Custom Authentication Integration
|
||||
|
||||
### Preserve API Key Authentication
|
||||
```csharp
|
||||
services.AddMcpServer(options =>
|
||||
{
|
||||
options.UseStdioTransport();
|
||||
options.UseHttpTransport();
|
||||
|
||||
// Custom authentication handler
|
||||
options.AddAuthentication<ApiKeyAuthenticationHandler>();
|
||||
});
|
||||
|
||||
public class ApiKeyAuthenticationHandler : IMcpAuthenticationHandler
|
||||
{
|
||||
private readonly IMcpApiKeyService _apiKeyService;
|
||||
private readonly ITenantContext _tenantContext;
|
||||
|
||||
public async Task<McpAuthenticationResult> AuthenticateAsync(
|
||||
McpRequest request,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// Extract API Key from header
|
||||
var apiKey = request.Headers["X-Api-Key"];
|
||||
|
||||
if (string.IsNullOrEmpty(apiKey))
|
||||
{
|
||||
return McpAuthenticationResult.Fail("API Key required");
|
||||
}
|
||||
|
||||
// Validate API Key (existing logic)
|
||||
var validationResult = await _apiKeyService.ValidateAsync(
|
||||
apiKey,
|
||||
cancellationToken);
|
||||
|
||||
if (!validationResult.IsValid)
|
||||
{
|
||||
return McpAuthenticationResult.Fail("Invalid API Key");
|
||||
}
|
||||
|
||||
// Setup TenantContext
|
||||
_tenantContext.SetTenant(validationResult.TenantId);
|
||||
|
||||
return McpAuthenticationResult.Success(new McpPrincipal
|
||||
{
|
||||
TenantId = validationResult.TenantId,
|
||||
UserId = validationResult.UserId,
|
||||
ApiKeyId = validationResult.ApiKeyId
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Preserve Field-Level Authorization
|
||||
```csharp
|
||||
services.AddMcpServer(options =>
|
||||
{
|
||||
// Custom authorization handler
|
||||
options.AddAuthorization<FieldLevelAuthorizationHandler>();
|
||||
});
|
||||
|
||||
public class FieldLevelAuthorizationHandler : IMcpAuthorizationHandler
|
||||
{
|
||||
private readonly IFieldPermissionService _fieldPermission;
|
||||
|
||||
public async Task<bool> AuthorizeAsync(
|
||||
McpPrincipal principal,
|
||||
string operation,
|
||||
object resource,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
// Check field-level permissions
|
||||
return await _fieldPermission.HasAccessAsync(
|
||||
principal.TenantId,
|
||||
principal.UserId,
|
||||
operation,
|
||||
resource,
|
||||
cancellationToken);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] stdio transport works (Claude Desktop compatible)
|
||||
- [ ] HTTP/SSE transport works (web client compatible)
|
||||
- [ ] API Key authentication functional
|
||||
- [ ] Field-level permissions enforced
|
||||
- [ ] Custom middleware removed (McpProtocolMiddleware, ApiKeyAuthMiddleware)
|
||||
- [ ] Zero breaking changes for existing MCP clients
|
||||
- [ ] CORS configured for web clients
|
||||
- [ ] SSE notifications working
|
||||
|
||||
## Tasks Breakdown
|
||||
|
||||
- [ ] [Task 1](sprint_5_story_16_task_1.md) - Configure SDK transports (stdio + HTTP/SSE) - 1 day
|
||||
- [ ] [Task 2](sprint_5_story_16_task_2.md) - Migrate API Key authentication to SDK pipeline - 1 day
|
||||
- [ ] [Task 3](sprint_5_story_16_task_3.md) - Migrate field-level authorization to SDK pipeline - 1 day
|
||||
- [ ] [Task 4](sprint_5_story_16_task_4.md) - Remove custom middleware and test end-to-end - 1 day
|
||||
- [ ] [Task 5](sprint_5_story_16_task_5.md) - CORS configuration and SSE notification testing - 1 day
|
||||
|
||||
**Progress**: 0/5 tasks completed (0%)
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### stdio Transport Tests
|
||||
- Claude Desktop connection
|
||||
- Tool calls via stdio
|
||||
- Resource queries via stdio
|
||||
- Error handling
|
||||
|
||||
### HTTP/SSE Transport Tests
|
||||
- HTTP POST endpoints
|
||||
- SSE connection establishment
|
||||
- Real-time notifications
|
||||
- CORS preflight requests
|
||||
|
||||
### Authentication Tests
|
||||
- Valid API Key
|
||||
- Invalid API Key
|
||||
- Expired API Key
|
||||
- Missing API Key
|
||||
|
||||
### Authorization Tests
|
||||
- Field-level permission checks
|
||||
- Unauthorized field access attempts
|
||||
|
||||
## Code to Remove
|
||||
|
||||
After migration complete:
|
||||
- `McpProtocolMiddleware.cs` (~150 lines)
|
||||
- `ApiKeyAuthMiddleware.cs` (~80 lines)
|
||||
- `McpEndpointRouting.cs` (~100 lines)
|
||||
|
||||
**Total**: ~330 lines removed
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- **Code Reduction**: -330 lines (middleware)
|
||||
- **Transport Support**: 2 transports (stdio + HTTP/SSE)
|
||||
- **Compatibility**: 100% (Claude Desktop + web clients)
|
||||
- **Performance**: No regression (<5ms overhead)
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] SDK transports configured (stdio + HTTP/SSE)
|
||||
- [ ] Custom middleware removed
|
||||
- [ ] API Key authentication working
|
||||
- [ ] Field-level permissions enforced
|
||||
- [ ] Integration tests pass (both transports)
|
||||
- [ ] Claude Desktop compatibility verified
|
||||
- [ ] Web client compatibility verified
|
||||
- [ ] Code reviewed and approved
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-11-09 by Product Manager Agent
|
||||
**Owner**: Backend Team
|
||||
**Start Date**: 2025-12-30 (Week 6)
|
||||
**Target Date**: 2026-01-03 (End of Week 6)
|
||||
**Status**: Not Started
|
||||
438
docs/plans/sprint_5_story_17.md
Normal file
438
docs/plans/sprint_5_story_17.md
Normal file
@@ -0,0 +1,438 @@
|
||||
---
|
||||
story_id: story_17
|
||||
sprint_id: sprint_5
|
||||
parent_story_id: story_0
|
||||
status: not_started
|
||||
priority: P0
|
||||
assignee: backend
|
||||
created_date: 2025-11-09
|
||||
estimated_days: 10
|
||||
phase: 5
|
||||
---
|
||||
|
||||
# Story 17: Testing, Optimization & Documentation
|
||||
|
||||
**Parent Epic**: [Story 0](sprint_5_story_0.md) - Integrate Microsoft .NET MCP SDK
|
||||
**Phase**: 5 - Testing & Optimization (Week 7-8)
|
||||
**Priority**: P0 - Critical
|
||||
**Estimated Effort**: 10 days (2 weeks)
|
||||
**Dependencies**: Story 16 (Transport migration complete)
|
||||
|
||||
## User Story
|
||||
|
||||
**As** a backend team lead,
|
||||
**I want** comprehensive testing, performance optimization, and documentation for MCP SDK integration,
|
||||
**So that** we have production-ready code with zero regressions and complete knowledge transfer.
|
||||
|
||||
## Business Value
|
||||
|
||||
- **Quality Assurance**: Zero CRITICAL bugs in production
|
||||
- **Performance Validation**: Confirm ≥20% improvement target met
|
||||
- **Security Confidence**: Pass security audit with zero HIGH vulnerabilities
|
||||
- **Team Knowledge**: Complete documentation for future maintenance
|
||||
- **Production Ready**: Confident deployment with rollback plan
|
||||
|
||||
## Week 7: Integration Testing & Bug Fixes
|
||||
|
||||
### 7.1 End-to-End Integration Testing (2 days)
|
||||
|
||||
**Test Scenarios**:
|
||||
|
||||
1. **Claude Desktop Integration** (stdio)
|
||||
- Initialize handshake
|
||||
- List Tools and Resources
|
||||
- Call each Tool (10 total)
|
||||
- Query each Resource (11 total)
|
||||
- Verify Diff Preview workflow
|
||||
- Test approval/rejection flow
|
||||
|
||||
2. **Web Client Integration** (HTTP/SSE)
|
||||
- HTTP POST requests to MCP endpoints
|
||||
- SSE connection for notifications
|
||||
- API Key authentication
|
||||
- CORS preflight handling
|
||||
|
||||
3. **Multi-Tenant Isolation**
|
||||
- Create 2 test tenants
|
||||
- Verify cross-tenant data access blocked
|
||||
- Test API Keys scoped to tenants
|
||||
- Validate Global Query Filters
|
||||
|
||||
4. **Error Handling**
|
||||
- Invalid API Key
|
||||
- Missing required parameters
|
||||
- Malformed JSON-RPC requests
|
||||
- Network failures (timeout, disconnect)
|
||||
|
||||
**Deliverables**:
|
||||
- Integration test suite (50+ test cases)
|
||||
- Test execution report
|
||||
- Bug tracking spreadsheet
|
||||
|
||||
---
|
||||
|
||||
### 7.2 Performance Testing & Optimization (2 days)
|
||||
|
||||
**Baseline vs. Target Performance**:
|
||||
|
||||
| Metric | Baseline (Custom) | Target (SDK) | Actual (Measured) |
|
||||
|--------|-------------------|--------------|-------------------|
|
||||
| Tool Execution (P95) | 150ms | 120ms (20% faster) | TBD |
|
||||
| Resource Query (P95) | 120ms | 85ms (30% faster) | TBD |
|
||||
| Throughput | 70 req/s | 100 req/s | TBD |
|
||||
| Memory Usage | 180 MB | 150 MB (15% less) | TBD |
|
||||
|
||||
**Performance Tests**:
|
||||
1. **Load Testing** (Apache Bench or k6)
|
||||
- 100 concurrent users
|
||||
- 1000 requests total
|
||||
- Measure P50, P95, P99 latency
|
||||
|
||||
2. **Memory Profiling** (dotMemory)
|
||||
- Baseline memory usage
|
||||
- Peak memory under load
|
||||
- Memory leak detection
|
||||
|
||||
3. **Database Query Performance**
|
||||
- EF Core query analysis
|
||||
- Index usage verification
|
||||
- N+1 query detection
|
||||
|
||||
**Optimization Tasks** (if needed):
|
||||
- Add missing database indexes
|
||||
- Optimize Redis cache keys
|
||||
- Tune connection pool sizes
|
||||
- Enable HTTP response compression
|
||||
|
||||
**Deliverables**:
|
||||
- Performance benchmark report
|
||||
- Optimization recommendations
|
||||
- Before/after comparison charts
|
||||
|
||||
---
|
||||
|
||||
### 7.3 Security Audit (1 day)
|
||||
|
||||
**Security Tests**:
|
||||
|
||||
1. **Authentication & Authorization**
|
||||
- API Key brute force attempt (rate limiting)
|
||||
- Expired API Key handling
|
||||
- Invalid API Key handling
|
||||
- Field-level permission bypass attempts
|
||||
|
||||
2. **Multi-Tenant Security**
|
||||
- Cross-tenant data access attempts
|
||||
- SQL injection attempts (parameterized queries)
|
||||
- JSONB injection attempts
|
||||
- Path traversal attempts (Resource URIs)
|
||||
|
||||
3. **Input Validation**
|
||||
- Tool parameter validation
|
||||
- Resource URI validation
|
||||
- JSON-RPC message validation
|
||||
- CSRF protection (HTTP transport)
|
||||
|
||||
4. **Sensitive Data Exposure**
|
||||
- Log scrubbing (no API Keys, passwords logged)
|
||||
- Error messages (no stack traces to clients)
|
||||
- HTTPS enforcement (production)
|
||||
|
||||
**Security Checklist**:
|
||||
- [ ] OWASP Top 10 compliance
|
||||
- [ ] API Key BCrypt hashed (never plaintext)
|
||||
- [ ] HTTPS only (production)
|
||||
- [ ] Rate limiting enabled
|
||||
- [ ] CORS properly configured
|
||||
- [ ] SQL injection protected (EF Core parameterized)
|
||||
- [ ] XSS protection (JSON escaping)
|
||||
- [ ] Sensitive data not logged
|
||||
|
||||
**Deliverables**:
|
||||
- Security audit report (PASS/FAIL per category)
|
||||
- Vulnerability remediation plan (if issues found)
|
||||
|
||||
---
|
||||
|
||||
### 7.4 Bug Fixes & Refinement (1 day)
|
||||
|
||||
**Bug Triage Process**:
|
||||
1. Categorize bugs (CRITICAL, HIGH, MEDIUM, LOW)
|
||||
2. Fix CRITICAL and HIGH bugs immediately
|
||||
3. Defer MEDIUM/LOW bugs to backlog (if not blocking)
|
||||
|
||||
**Expected Bug Types**:
|
||||
- Integration test failures
|
||||
- Performance bottlenecks
|
||||
- Edge case handling (null values, empty lists)
|
||||
- Error message clarity
|
||||
|
||||
**Deliverables**:
|
||||
- Bug fix commits
|
||||
- Updated test suite (all passing)
|
||||
|
||||
---
|
||||
|
||||
## Week 8: Documentation & Production Readiness
|
||||
|
||||
### 8.1 Architecture Documentation Update (2 days)
|
||||
|
||||
**Documents to Update**:
|
||||
|
||||
1. **MCP Server Architecture** (`docs/architecture/mcp-server-architecture.md`)
|
||||
- Add SDK integration section (500+ lines)
|
||||
- Update component diagrams
|
||||
- Document hybrid architecture decisions
|
||||
- Add SDK vs. Custom comparison table
|
||||
|
||||
2. **SDK Migration Guide** (`docs/guides/mcp-sdk-migration.md`) - NEW
|
||||
- Step-by-step migration instructions
|
||||
- Code examples (before/after)
|
||||
- Common pitfalls and solutions
|
||||
- Troubleshooting guide
|
||||
|
||||
3. **ADR: MCP SDK Adoption** (`docs/architecture/adr/005-mcp-sdk-adoption.md`) - NEW
|
||||
- Decision context
|
||||
- Options considered
|
||||
- Decision rationale
|
||||
- Consequences and trade-offs
|
||||
|
||||
**Deliverables**:
|
||||
- 3 updated/new documents (1500+ lines total)
|
||||
- Architecture diagrams (Mermaid or Draw.io)
|
||||
- Code examples repository
|
||||
|
||||
---
|
||||
|
||||
### 8.2 API Documentation (1 day)
|
||||
|
||||
**OpenAPI/Swagger Updates**:
|
||||
|
||||
1. **Tool Endpoints**
|
||||
- Document all 10 Tools
|
||||
- Parameter schemas
|
||||
- Response examples
|
||||
- Error codes
|
||||
|
||||
2. **Resource Endpoints**
|
||||
- Document all 11 Resources
|
||||
- URI patterns
|
||||
- Query parameters
|
||||
- Response formats
|
||||
|
||||
3. **Authentication**
|
||||
- API Key header format
|
||||
- Error responses (401, 403)
|
||||
- Rate limiting headers
|
||||
|
||||
**Example Swagger Annotation**:
|
||||
```csharp
|
||||
[McpTool(Name = "create_issue")]
|
||||
[SwaggerOperation(
|
||||
Summary = "Create a new issue",
|
||||
Description = "Creates Epic/Story/Task with Diff Preview approval workflow"
|
||||
)]
|
||||
[SwaggerResponse(200, "Pending change created", typeof(PendingChangeDto))]
|
||||
[SwaggerResponse(400, "Invalid parameters")]
|
||||
[SwaggerResponse(401, "Unauthorized")]
|
||||
public class CreateIssueTool { ... }
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
- Complete Swagger/OpenAPI spec
|
||||
- Interactive API documentation (Swagger UI)
|
||||
|
||||
---
|
||||
|
||||
### 8.3 Code Cleanup (1 day)
|
||||
|
||||
**Cleanup Tasks**:
|
||||
|
||||
1. **Remove Old Code**
|
||||
- Delete `McpProtocolMiddleware.cs`
|
||||
- Delete `ApiKeyAuthMiddleware.cs`
|
||||
- Delete `IMcpTool.cs` interface
|
||||
- Delete `IMcpResource.cs` interface
|
||||
- Remove obsolete NuGet packages
|
||||
|
||||
2. **Update Code Comments**
|
||||
- Add XML documentation to public APIs
|
||||
- Update inline comments
|
||||
- Remove TODO/FIXME comments
|
||||
|
||||
3. **Code Style Enforcement**
|
||||
- Run `dotnet format`
|
||||
- Fix StyleCop warnings
|
||||
- Consistent naming conventions
|
||||
|
||||
4. **Dependency Audit**
|
||||
- Remove unused NuGet packages
|
||||
- Update vulnerable packages
|
||||
- Lock SDK version (avoid auto-updates)
|
||||
|
||||
**Deliverables**:
|
||||
- Clean codebase (zero warnings)
|
||||
- Updated `.csproj` files
|
||||
- Dependency lock file
|
||||
|
||||
---
|
||||
|
||||
### 8.4 Production Readiness & Deployment (2 days)
|
||||
|
||||
**Production Readiness Checklist**:
|
||||
|
||||
- [ ] **Testing**
|
||||
- [ ] All integration tests pass (>80% coverage)
|
||||
- [ ] Performance benchmarks meet targets
|
||||
- [ ] Security audit passed (0 CRITICAL, 0 HIGH)
|
||||
|
||||
- [ ] **Documentation**
|
||||
- [ ] Architecture docs updated
|
||||
- [ ] API docs complete
|
||||
- [ ] Migration guide published
|
||||
|
||||
- [ ] **Code Quality**
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] Zero StyleCop warnings
|
||||
- [ ] No TODO/FIXME comments
|
||||
|
||||
- [ ] **Configuration**
|
||||
- [ ] Environment variables documented
|
||||
- [ ] Secrets managed (Azure Key Vault / AWS Secrets Manager)
|
||||
- [ ] Feature flags configured
|
||||
|
||||
- [ ] **Deployment**
|
||||
- [ ] Staging deployment successful
|
||||
- [ ] Smoke tests passed
|
||||
- [ ] Rollback plan documented
|
||||
|
||||
**Staging Deployment**:
|
||||
1. Deploy to staging environment
|
||||
2. Run smoke tests (5 critical scenarios)
|
||||
3. Monitor logs for errors
|
||||
4. Validate performance metrics
|
||||
|
||||
**Smoke Test Scenarios**:
|
||||
- Claude Desktop can connect (stdio)
|
||||
- Web client can connect (HTTP/SSE)
|
||||
- Create issue Tool works
|
||||
- List projects Resource works
|
||||
- Diff Preview approval flow works
|
||||
|
||||
**Rollback Plan**:
|
||||
- Database: No schema changes (safe to rollback)
|
||||
- Code: Git tag before deployment, revert if needed
|
||||
- Configuration: Feature flag to disable SDK (fallback to custom)
|
||||
|
||||
**Deliverables**:
|
||||
- Production readiness report (PASS/FAIL)
|
||||
- Staging deployment success confirmation
|
||||
- Rollback plan document
|
||||
|
||||
---
|
||||
|
||||
### 8.5 Final Code Review & Sign-Off (1 day)
|
||||
|
||||
**Review Checklist**:
|
||||
- [ ] Architect review (architecture compliance)
|
||||
- [ ] Tech lead review (code quality)
|
||||
- [ ] Security review (security best practices)
|
||||
- [ ] QA review (test coverage)
|
||||
- [ ] Product manager sign-off (business value delivered)
|
||||
|
||||
**Sign-Off Criteria**:
|
||||
- All acceptance criteria met (Epic level)
|
||||
- Performance targets achieved (≥20% improvement)
|
||||
- Security audit passed (0 CRITICAL, 0 HIGH)
|
||||
- Documentation complete
|
||||
- Production deployment plan approved
|
||||
|
||||
**Deliverables**:
|
||||
- Code review approval
|
||||
- Sign-off document (all stakeholders)
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Testing
|
||||
- [ ] Integration test suite complete (50+ tests)
|
||||
- [ ] All integration tests pass (100%)
|
||||
- [ ] Performance benchmarks meet targets (≥20% improvement)
|
||||
- [ ] Security audit passed (0 CRITICAL, 0 HIGH)
|
||||
|
||||
### Documentation
|
||||
- [ ] Architecture docs updated (1500+ lines)
|
||||
- [ ] API docs complete (Swagger)
|
||||
- [ ] Migration guide published
|
||||
- [ ] ADR documented
|
||||
|
||||
### Code Quality
|
||||
- [ ] Old code removed (330+ lines)
|
||||
- [ ] Zero StyleCop warnings
|
||||
- [ ] XML documentation complete
|
||||
- [ ] Code reviewed and approved
|
||||
|
||||
### Production Readiness
|
||||
- [ ] Staging deployment successful
|
||||
- [ ] Smoke tests passed
|
||||
- [ ] Rollback plan documented
|
||||
- [ ] All stakeholders signed off
|
||||
|
||||
## Tasks Breakdown
|
||||
|
||||
### Week 7: Testing & Optimization
|
||||
- [ ] [Task 1](sprint_5_story_17_task_1.md) - End-to-end integration testing - 2 days
|
||||
- [ ] [Task 2](sprint_5_story_17_task_2.md) - Performance testing and optimization - 2 days
|
||||
- [ ] [Task 3](sprint_5_story_17_task_3.md) - Security audit - 1 day
|
||||
- [ ] [Task 4](sprint_5_story_17_task_4.md) - Bug fixes and refinement - 1 day
|
||||
|
||||
### Week 8: Documentation & Deployment
|
||||
- [ ] [Task 5](sprint_5_story_17_task_5.md) - Architecture documentation update - 2 days
|
||||
- [ ] [Task 6](sprint_5_story_17_task_6.md) - API documentation (Swagger) - 1 day
|
||||
- [ ] [Task 7](sprint_5_story_17_task_7.md) - Code cleanup - 1 day
|
||||
- [ ] [Task 8](sprint_5_story_17_task_8.md) - Production readiness and staging deployment - 2 days
|
||||
- [ ] [Task 9](sprint_5_story_17_task_9.md) - Final code review and sign-off - 1 day
|
||||
|
||||
**Progress**: 0/9 tasks completed (0%)
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Quality Metrics
|
||||
- **Test Coverage**: ≥80%
|
||||
- **Integration Tests**: 50+ tests, 100% passing
|
||||
- **Security**: 0 CRITICAL, 0 HIGH vulnerabilities
|
||||
- **Code Quality**: 0 StyleCop warnings
|
||||
|
||||
### Performance Metrics
|
||||
- **Tool Execution**: ≥20% faster (target: 120ms P95)
|
||||
- **Resource Query**: ≥30% faster (target: 85ms P95)
|
||||
- **Throughput**: ≥100 req/s (vs. 70 baseline)
|
||||
- **Memory**: ≤150 MB (vs. 180 baseline)
|
||||
|
||||
### Documentation Metrics
|
||||
- **Architecture Docs**: 1500+ lines updated
|
||||
- **API Docs**: 100% Swagger coverage
|
||||
- **Migration Guide**: Complete step-by-step
|
||||
- **Code Examples**: 10+ before/after samples
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All Week 7 tasks complete (testing, optimization, security, bug fixes)
|
||||
- [ ] All Week 8 tasks complete (docs, cleanup, deployment, sign-off)
|
||||
- [ ] Integration tests pass (100%)
|
||||
- [ ] Performance targets met (≥20% improvement)
|
||||
- [ ] Security audit passed (0 CRITICAL, 0 HIGH)
|
||||
- [ ] Documentation complete (architecture, API, migration guide)
|
||||
- [ ] Code cleanup complete (old code removed, warnings fixed)
|
||||
- [ ] Staging deployment successful
|
||||
- [ ] Smoke tests passed
|
||||
- [ ] All stakeholders signed off
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-11-09 by Product Manager Agent
|
||||
**Owner**: Backend Team Lead
|
||||
**Start Date**: 2026-01-06 (Week 7)
|
||||
**Target Date**: 2026-01-17 (End of Week 8)
|
||||
**Status**: Not Started
|
||||
Reference in New Issue
Block a user