# Unified Roadmap: mcp-common + session-buddy

**Date**: 2025-10-28
**Duration**: 16 weeks
**Status**: Week 2 Days 1-3 (HTTPClientAdapter implementation)

______________________________________________________________________

## Overview

This roadmap unifies two complementary efforts:

1. **mcp-common**: ACB-native foundation library for 9 MCP servers
1. **session-buddy**: Pilot implementation and validation sandbox

**Key Insight**: session-buddy validates patterns BEFORE they're extracted to mcp-common and rolled out ecosystem-wide.

______________________________________________________________________

## Work Stream Organization

### 🔴 Track 1: Critical Path (Serial)

**Focus**: Foundation validation in session-buddy → extraction to mcp-common → ecosystem rollout
**Timeline**: Weeks 1-6
**Priority**: HIGHEST - Blocks 8 other servers

### 🟡 Track 2: Parallel Infrastructure

**Focus**: Non-blocking infrastructure development
**Timeline**: Weeks 3-5
**Priority**: HIGH - Quality improvements

### 🟢 Track 3: Deep Integration

**Focus**: session-buddy advanced features
**Timeline**: Weeks 7-16
**Priority**: MEDIUM - After foundations complete

______________________________________________________________________

## Week-by-Week Roadmap

### Week 1: ACB Foundation ✅ **COMPLETE**

**Track 1 (Critical Path)**:

- [x] Install ACB framework (`uv add "acb>=0.25.2"`)
- [x] Enable coverage ratchet (35% minimum)
- [x] Enable complexity checks (remove C901 ignore)
- [x] Consolidate config.py with ACB config system (-558 lines)

**Track 2 (Parallel)**:

- [x] Create test stubs for 7 zero-coverage files

**Deliverables**:

- ✅ ACB framework operational
- ✅ Config system ACB-native
- ✅ Coverage ratchet protecting quality

**Status**: ✅ Complete | **Ecosystem Impact**: Foundation established

______________________________________________________________________

### Week 2: HTTPClientAdapter Validation 🔄 **IN PROGRESS**

**Track 1 (Critical Path)**:

- [x] Day 1-3: Implement HTTPClientAdapter in session-buddy ✅ **DONE**
- [ ] Day 4: Load testing (validate 11x performance improvement)
- [ ] Day 5: Integration testing with real traffic patterns
- [ ] Document HTTPClientAdapter patterns for extraction

**Track 2 (Parallel)**:

- [ ] Create testing utilities documentation
- [ ] Begin cache adapter replacement planning

**Deliverables**:

- ✅ HTTPClientAdapter implemented and validated
- ✅ Performance benchmarks showing 11x improvement
- ✅ Integration tests passing
- ✅ Pattern documentation for mcp-common extraction

**Status**: 60% complete | **Blockers**: None | **Risk**: 🟢 Low

**Critical**: This blocks mailgun critical bug fix (Week 3)

______________________________________________________________________

### Week 3: Extraction + Critical Bug Fixes

**Track 1 (Critical Path)**:

- [ ] Day 1: Extract HTTPClientAdapter to mcp-common
- [ ] Day 2-3: Fix mailgun-mcp critical bug (HTTP client reuse)
  - Apply HTTPClientAdapter
  - Validate 10x performance improvement
  - Integration testing
- [ ] Day 4-5: Apply HTTPClientAdapter to 5 remaining standalone servers
  - unifi-mcp (also fix tool registration)
  - excalidraw-mcp (also fix hardcoded paths)
  - opera-cloud-mcp
  - raindropio-mcp (already best practices, minimal changes)
  - session-buddy (already using it)

**Track 2 (Parallel)**:

- [ ] Extract RateLimiter from crackerjack/mcp/rate_limiter.py
- [ ] Begin security adapter development (sanitization/filtering)

**Deliverables**:

- ✅ mcp-common v2.0.0-alpha released (HTTPClientAdapter)
- ✅ mailgun-mcp bug fixed (critical)
- ✅ unifi-mcp tools working
- ✅ excalidraw-mcp portable
- ✅ RateLimiter in mcp-common

**Status**: Not started | **Blockers**: Week 2 completion | **Risk**: 🟡 Medium

**Impact**: 6/9 servers using HTTPClientAdapter, 3 critical bugs fixed

______________________________________________________________________

### Week 4: DI Validation + Pattern Extraction

**Track 1 (Critical Path)**:

- [ ] Day 1-3: session-buddy Phase 2.7 - ACB Dependency Injection
  - Implement `session_buddy/di/` package
  - Apply `depends.inject` to core, quality, tool layers
  - Migration: Server core, tool modules to DI
- [ ] Day 4: Validate DI patterns (70%+ coverage on new code)
- [ ] Day 5: Extract DI patterns to `mcp-common/di/`

**Track 2 (Parallel)**:

- [ ] Extract health check pattern to `mcp-common/health.py`
- [ ] Complete security adapters (SanitizerAdapter, FilterAdapter)
- [ ] Testing utilities finalization

**Deliverables**:

- ✅ Phase 2.7 complete (DI operational in session-buddy)
- ✅ mcp-common v2.0.0-beta released (HTTP, DI, health)
- ✅ Security adapters implemented
- ✅ Pattern documentation complete

**Status**: Not started | **Blockers**: Week 3 completion | **Risk**: 🟡 Medium

**Milestone 1 Gate**: Foundation Validated

- If passed → proceed with ecosystem rollout
- If failed → delay 1 week, fix issues

______________________________________________________________________

### Week 5: Ecosystem Rollout (Part 1)

**Track 1 (Critical Path)**:

- [ ] Day 1-2: Apply DI patterns to 3 standalone servers
  - mailgun-mcp (already using HTTPClientAdapter)
  - opera-cloud-mcp
  - raindropio-mcp (minor changes)
- [ ] Day 3-5: Extract shutdown coordinator pattern
  - Document graceful shutdown from session-buddy
  - Add to `mcp-common/lifecycle/shutdown.py`

**Track 2 (Parallel)**:

- [ ] Replicate health checks across ecosystem (2 hours per server)
- [ ] Replicate shutdown handlers (1 hour per server)

**Deliverables**:

- ✅ 3 servers with full mcp-common adoption
- ✅ Shutdown coordinator in mcp-common
- ✅ Health checks deployed ecosystem-wide

**Status**: Not started | **Blockers**: Week 4 completion | **Risk**: 🟢 Low

______________________________________________________________________

### Week 6: Ecosystem Rollout (Part 2)

**Track 1 (Critical Path)**:

- [ ] Day 1-3: Apply DI + patterns to remaining servers
  - unifi-mcp (most complex, thorough testing needed)
  - excalidraw-mcp (hybrid Python/TypeScript architecture)
  - session-buddy (already using patterns, formalize)
- [ ] Day 4: ACB-integrated servers enhancement
  - Add rate limiting to ACB mcp
  - Simplify crackerjack mcp (use shared RateLimiter)
  - FastBlocks inherits improvements via ACB
- [ ] Day 5: mcp-common v2.0.0 final release

**Deliverables**:

- ✅ All 9 servers using mcp-common v2.0.0
- ✅ Ecosystem health: 74 → 82 (+8 points)
- ✅ mcp-common v2.0.0 production release

**Status**: Not started | **Blockers**: Week 5 completion | **Risk**: 🟢 Low

**Milestone 2 Gate**: Ecosystem Adoption Complete

- If passed → session-buddy continues Phase 3
- If failed → extend ecosystem work 1 week

**🎉 MAJOR MILESTONE**: mcp-common foundation deployed across all 9 servers!

______________________________________________________________________

### Week 7-8: Template-Based Formatting (session-buddy Phase 3.1)

**Track 3 (Deep Integration)**:

- [ ] Week 7: Build `session_buddy/templates/` hierarchy
  - Register Jinja2 loader via DI
  - Document data models for template families
  - Create TemplateRenderer service
- [ ] Week 8: Migrate formatting functions to templates
  - 128 functions from `utils/server_helpers.py`
  - Quality engine formatters
  - Snapshot testing for regression detection

**Deliverables**:

- ✅ Template bundle with versioned naming
- ✅ Renderer service with caching
- ✅ 128 formatting functions replaced (-2,500 lines)
- ✅ Golden transcript tests passing

**Status**: Not started | **Blockers**: Week 6 completion | **Risk**: 🟢 Low

**LOC Impact**: 28,113 → 25,613 (-8.9%)

______________________________________________________________________

### Week 9-10: Universal Query Interface (session-buddy Phase 3.2)

**Track 3 (Deep Integration)**:

- [ ] Week 9: Create `session_buddy/adapters/database.py`
  - ACB query client with connection pooling
  - Query composition helpers
  - Parameterized builders
- [ ] Week 10: Convert query consumers
  - `reflection_tools.py` to query adapter
  - Analytics modules
  - Scoring helpers
  - Integration tests (80% coverage target)

**Deliverables**:

- ✅ ACB-backed query adapter operational
- ✅ Refactored modules using abstractions
- ✅ Query layer documentation
- ✅ Load test validation (10 concurrent queries)

**Status**: Not started | **Blockers**: Week 8 completion | **Risk**: 🟡 Medium

**LOC Impact**: 25,613 → 24,613 (-3.9%)

**Optional**: Evaluate DuckPGQ knowledge graph for mcp-common extraction

______________________________________________________________________

### Week 11-12: Event-Driven Orchestration (session-buddy Phase 3.3)

**Track 3 (Deep Integration)**:

- [ ] Week 11: Map lifecycle hooks to EventBus
  - Define canonical event schema
  - Implement `session_buddy/events.py`
  - EventBus configuration via DI
- [ ] Week 12: Refactor listeners
  - Server core subscribers
  - Monitoring module subscribers
  - Notification module subscribers
  - Add telemetry and replay protection

**Deliverables**:

- ✅ Event schema catalog
- ✅ EventBus configuration
- ✅ Subscriber modules with metrics
- ✅ End-to-end scenario tests

**Status**: Not started | **Blockers**: Week 10 completion | **Risk**: 🟡 Medium

**LOC Impact**: 24,613 → 22,613 (-8.1%)

**ACB Integration**: 0/10 → 9/10 ✅

______________________________________________________________________

### Week 13-14: Test Coverage Sprint (session-buddy Phase 4)

**Track 3 (Excellence)**:

- [ ] Week 13: Systematic test creation
  - All untested paths
  - Integration test expansion
  - Property-based tests (Hypothesis)
- [ ] Week 14: Advanced testing
  - Performance regression tests
  - Chaos engineering tests
  - Mutation testing validation

**Deliverables**:

- ✅ Test coverage: 34.6% → 70%
- ✅ Integration test suite expanded
- ✅ Chaos tests validating resilience
- ✅ Mutation testing score 80%+

**Status**: Not started | **Blockers**: Week 12 completion | **Risk**: 🟢 Low

**Quality Impact**: Coverage ratchet protecting improvements

______________________________________________________________________

### Week 15-16: Performance & Polish (session-buddy Phase 4)

**Track 3 (Excellence)**:

- [ ] Week 15: ACB-enabled optimizations
  - Performance profiling
  - Query optimization
  - Cache tuning
  - Memory optimization
- [ ] Week 16: Production preparation
  - Documentation updates
  - API reference completion
  - Deployment guide
  - Production monitoring setup

**Deliverables**:

- ✅ Performance improved (+30-50%)
- ✅ Test coverage: 70% → 85%+
- ✅ Quality score: 71 → 95 (+24)
- ✅ Production deployment ready
- ✅ Comprehensive documentation

**Status**: Not started | **Blockers**: Week 14 completion | **Risk**: 🟢 Low

**🎉 FINAL MILESTONE**: World-class reference implementation achieved!

______________________________________________________________________

## Milestone Checkpoints

### Milestone 1: Foundation Validated (End of Week 4)

**Gate Criteria**:

- [ ] HTTPClientAdapter proven (11x performance improvement)
- [ ] DI patterns validated (Phase 2.7 complete)
- [ ] mcp-common v2.0.0-beta released
- [ ] session-buddy using mcp-common adapters

**Go/No-Go Decision**:

- **GO**: Proceed with ecosystem rollout (Weeks 5-6)
- **NO-GO**: Delay 1 week, fix issues, re-evaluate

**Status**: Scheduled for end of Week 4

______________________________________________________________________

### Milestone 2: Ecosystem Adoption (End of Week 6)

**Gate Criteria**:

- [ ] All 9 servers using HTTPClientAdapter
- [ ] mailgun-mcp critical bug fixed (10x improvement)
- [ ] unifi-mcp tools registered and working
- [ ] excalidraw-mcp portable (no hardcoded paths)
- [ ] Health checks + shutdown replicated
- [ ] mcp-common v2.0.0 final release

**Go/No-Go Decision**:

- **GO**: session-buddy continues Phase 3 (deep integration)
- **NO-GO**: Extend ecosystem rollout, address issues

**Status**: Scheduled for end of Week 6

**Success Metrics**:

- Ecosystem health: 74 → 82 (+8)
- Critical bugs: 3 → 0
- Servers with rate limiting: 2/9 → 9/9
- Code duplication: Reduced by 50%

______________________________________________________________________

### Milestone 3: Excellence (End of Week 16)

**Gate Criteria**:

- [ ] session-buddy quality score 95/100
- [ ] Test coverage 85%+
- [ ] ACB integration 9/10
- [ ] Production ready
- [ ] Performance optimized (+30-50%)
- [ ] Documentation complete

**Success Criteria**:

- session-buddy is world-class reference implementation
- Ecosystem average quality 85/100
- Zero critical issues across all 9 servers

**Status**: Scheduled for end of Week 16

______________________________________________________________________

## Success Metrics Dashboard

### Current State (Week 2)

```
session-buddy Metrics
├── Quality Score:        71/100
├── Architecture:         90/100 ✅ (modular)
├── ACB Integration:      0/10 (Phase 2.7 starting)
├── Test Coverage:        34.6%
└── LOC:                  28,113

mcp-common Metrics
├── Status:               Week 2 Days 1-3
├── HTTPClientAdapter:    🔄 Implementing
├── Version:              Not yet released
└── Servers Adopted:      0/9 (session-buddy testing)

Ecosystem Metrics
├── Average Health:       74/100
├── Critical Bugs:        3 (mailgun, unifi, excalidraw)
├── Servers w/ Rate Limit: 2/9 (22%)
└── Code Duplication:     High
```

### Target State (Week 6 - Milestone 2)

```
session-buddy Metrics
├── Quality Score:        75/100 (+4)
├── Architecture:         90/100 (maintained)
├── ACB Integration:      6/10 (+6)
├── Test Coverage:        55% (+20.4pp)
└── LOC:                  28,113 (stable)

mcp-common Metrics
├── Status:               v2.0.0 released
├── HTTPClientAdapter:    ✅ Production
├── Version:              2.0.0
└── Servers Adopted:      9/9 (100%)

Ecosystem Metrics
├── Average Health:       82/100 (+8)
├── Critical Bugs:        0 (-3)
├── Servers w/ Rate Limit: 9/9 (100%)
└── Code Duplication:     -50%
```

### Final State (Week 16 - Milestone 3)

```
session-buddy Metrics
├── Quality Score:        95/100 (+24 from start)
├── Architecture:         95/100 (+5)
├── ACB Integration:      9/10 (+9)
├── Test Coverage:        85%+ (+50.4pp)
└── LOC:                  16,000 (-43%)

mcp-common Metrics
├── Status:               v2.0.0 stable
├── HTTPClientAdapter:    ✅ Proven
├── Version:              2.0.0
└── Servers Adopted:      9/9 (100%)

Ecosystem Metrics
├── Average Health:       85/100 (+11)
├── Critical Bugs:        0
├── Servers w/ Rate Limit: 9/9 (100%)
└── Code Duplication:     -70%
```

______________________________________________________________________

## Risk Matrix

| Risk | Probability | Impact | Week | Mitigation |
|------|------------|---------|------|------------|
| **HTTPClientAdapter validation delays** | 🟡 Medium (20%) | 🔴 High | 2 | Load testing, fallback plan |
| **mailgun fix complications** | 🟢 Low (10%) | 🔴 High | 3 | HTTPClientAdapter proven first |
| **DI pattern complexity** | 🟡 Medium (25%) | 🟡 Medium | 4 | Simple cases first, gradual adoption |
| **Ecosystem rollout issues** | 🟢 Low (15%) | 🟡 Medium | 5-6 | Incremental per-server rollout |
| **Template migration bugs** | 🟡 Medium (20%) | 🟢 Low | 7-8 | Snapshot testing, gradual migration |
| **Query interface regressions** | 🟡 Medium (25%) | 🟡 Medium | 9-10 | Output validation, benchmarking |
| **Event system race conditions** | 🟡 Medium (30%) | 🔴 High | 11-12 | Parallel run, extensive testing |
| **Test coverage timeline pressure** | 🟢 Low (15%) | 🟢 Low | 13-14 | Coverage is additive, can extend |
| **Overall Risk** | 🟢 **LOW** | - | - | Clear critical path, proven patterns |

### Risk Mitigation Strategy

**General Principles**:

1. ✅ **Feature flags** - All major changes behind toggles
1. ✅ **Parallel running** - Old and new systems during transition
1. ✅ **Incremental migration** - Never big-bang changes
1. ✅ **70%+ coverage** - All new code before merge
1. ✅ **Monitoring** - Metrics for all critical paths

**Emergency Rollback**:

- Git tags: `phase-1-complete`, `phase-2-complete`, etc.
- Toggle flags: `ACB_CONFIG`, `ACB_CACHE`, `ACB_DI`, etc.
- Original code retained 4 weeks post-migration

______________________________________________________________________

## Key Decisions & Trade-offs

### Decision 1: session-buddy as Pilot

**Rationale**: Most complex standalone server, best validation for ecosystem patterns
**Trade-off**: Delays session-buddy Phase 3 work, but de-risks ecosystem
**Status**: ✅ Validated - Phase 2 completion proves value

### Decision 2: Extract Health Checks + Shutdown

**Rationale**: "Extra" work proves production-ready patterns
**Trade-off**: Adds 2-3 hours per server to rollout (acceptable)
**Status**: ✅ Approved - Integration into unified plan (Week 4-5)

### Decision 3: Templates in session-buddy Only

**Rationale**: Unique to session-buddy's verbose output formatting needs
**Trade-off**: Not extracted to mcp-common (may reconsider later)
**Status**: 🟡 Deferred - Evaluate at Week 9 for potential extraction

### Decision 4: DuckPGQ as Optional Feature

**Rationale**: Knowledge graph pattern valuable but not universal
**Trade-off**: Not all 9 servers need semantic memory
**Status**: 🟡 Optional - Document as optional mcp-common feature (Week 9)

______________________________________________________________________

## Dependencies External to Plan

### Python Ecosystem

- **Python 3.13+** - Required for modern type hints
- **ACB ≥0.25.2** - Framework foundation
- **DuckDB** - Already in dependencies (no new deps)

### Development Tools

- **UV package manager** - For ACB and dependency management
- **pytest + hypothesis** - Testing framework
- **crackerjack** - Code quality enforcement

### Infrastructure

- **Git 2.30+** - For worktree features
- **8GB+ RAM** - For embedding model
- **10GB+ disk** - For test data

**Status**: ✅ All dependencies already met in session-buddy

______________________________________________________________________

## Communication & Coordination

### Weekly Progress Updates

**Schedule**: Every Friday EOD
**Format**: Markdown report with metrics dashboard
**Distribution**: Architecture Council (you)

**Template**:

```markdown
## Week N Progress Report
**Track 1 (Critical Path)**: [Status]
**Track 2 (Parallel)**: [Status]
**Track 3 (Deep Work)**: [Status]

**Completed**:
- [x] Item 1
- [x] Item 2

**In Progress**:
- [ ] Item 3

**Blocked**:
- [ ] Item 4 (blocker: reason)

**Metrics**:
- Quality: X/100 (ΔY)
- Coverage: X% (ΔY%)
- LOC: X (ΔY)

**Next Week Focus**: [Priority items]
```

### Milestone Reviews

**Schedule**: End of Weeks 4, 6, 16
**Format**: Architecture Council review session
**Deliverables**: Go/No-Go decision, risk reassessment

### Risk Reviews

**Schedule**: Bi-weekly (every 2 weeks)
**Format**: Risk matrix update
**Action**: Update mitigation strategies

______________________________________________________________________

## Appendices

### Appendix A: HTTPClientAdapter Validation Criteria

**Checklist for Week 2 Day 4-5**:

- [ ] Load test: 100 concurrent requests sustained
- [ ] Performance: 11x improvement vs. baseline
- [ ] Connection pooling: Max 100 connections, reuse validated
- [ ] Error handling: Timeout, retry, circuit breaker tested
- [ ] Memory: No leaks over 1000 requests
- [ ] Integration: Works with all session-buddy MCP tools

### Appendix B: DI Pattern Validation Criteria

**Checklist for Week 4**:

- [ ] Simple injection: Logger, config working
- [ ] Complex injection: Database, HTTP client working
- [ ] Override pattern: Tests can mock dependencies
- [ ] Lifecycle: Async resources properly managed
- [ ] Coverage: ≥70% on new DI code
- [ ] Documentation: Pattern guide with examples

### Appendix C: Ecosystem Rollout Checklist

**Per Server**:

- [ ] Install mcp-common≥2.0.0
- [ ] Register package with ACB (`register_pkg`)
- [ ] Migrate to MCPBaseSettings
- [ ] Use HTTPClientAdapter via DI
- [ ] Add rate limiting (`@rate_limit`)
- [ ] Add security adapters (sanitize/filter)
- [ ] Write tests with DI mocking
- [ ] Add ServerPanels for UI
- [ ] Update documentation
- [ ] Health checks operational
- [ ] Graceful shutdown working

### Appendix D: Quality Gates

**Every Commit**:

- [ ] Ruff, Pyright, Bandit passing
- [ ] Complexity ≤15 per function
- [ ] Coverage maintained or increased
- [ ] Tests passing

**Every Phase**:

- [ ] Architecture review
- [ ] Performance benchmarks
- [ ] Integration tests passing
- [ ] Documentation updated

______________________________________________________________________

**Document Status**: 🟢 **ACTIVE ROADMAP**
**Next Review**: End of Week 4 (Milestone 1)
**Owner**: Architecture Council
**Last Updated**: 2025-10-28
